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This document describes configurations of the Alto/Mesa system software and the individual 
components which comprise them. These components include runtime support for the language, 
routines for manipulating the Alto display, keyboard, and file system, facilities for loading client 
programs and building new systems, and a number of useful common software packages. 

Suggestions as to the form, correctness, and understandability of this material should be funneled 
through your support group. All of us involved in the development of Mesa welcome feedback 
and suggestions on both the language and the system and debugging environment. 
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1. Overview 



The Mesa environment contains all of the facilities described in this document Section 2 
contains an enumeration of the definitions modules available in the Alto/Mesa system; it 
includes a brief description of the facilities provided by each interface. Complete documentation 
can be found in Section 5. 

Section 3 describes the various configurations and optional packages that comprise the Alto/Mesa 
system. Two configurations of the system are available: the standard one, which includes most of 
the facilities described here, and a more basic one, containing only required runtime and file 
system support (it contains no display or keyboard software, for example). A number of optional 
packages are available for use with the basic system, so that the Mesa system can be tailored to 
each application. 

The Mesa Executive (Section 4) is a simple (and small) user interface supporting only a few 
commands. It allows only program loading, state saving, and debugger communication; more 
complicated operations must be provided by the user or by one of the standard packages that is 
available separately. The Mesa Executive also supports command line input in both the standard 
and the basic system; this allows the user interface to be completely controlled by the application. 

Finally, the bulk of this manual (Section 5) contains detailed descriptions of each of the packages 
summarized in Section 2. 

Further details are available elsewhere on the language {Mesa Language Manual) and the 
debugger {Mesa Debugger Documentation). Information on obtaining and running the system is 
contained in the Mesa User's Handbook, 
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2. Definitions and Interfaces 



The following list enumerates the public system modules of interest to Alto/Mesa programmers. 
The interface name is followed by the title of the section of this document (or other reference 
material) which describes the facilities the interface provides. The parenthesized names 
following the definitions module identify the programs which implement that interface — the 
ultimate documentation after all. 

allocdefs (swapper) Segment Package 

Low level memory allocation functions are defined here. Complete control of segment allocation 
and swapping can be obtained using this interface. 

altodefs (Hardware) Mesa Language Manual 

Contains a number of machine dependent constants describing physical characteristics of the 
Alto and its basic data types (bits per character, characters per word, etc.). 

altofiledefs (BCPL) Alto Operating System Reference Manual 

Defines the data structures (but not the operations) used in manipulating the Alto file system. 
Note that these structures are shared by several software systems running on the Alto. 

bitbltdefs (Hardware) Alto: A Personal Computer System; Hardware Manual 

Provides a Mesa definition of the hardware BitBlt (bit boundary block transfer) operation. 

directorydefs (directory) Directory Package 

Common operations on the Alto's file directory are defined here; they are all based on a single 
primitive which enumerates entries in the directory. 

displaydefs (systemdisplay, displaycontrol) Display Package 

Provides device-dependent operations for the display. Simple operations are implemented using 
the standard stream interface (see streamdefs). 

doubledefs (double) Miscellaneous 

Contains a complete set of procedures for operating on long (double precision) cardinals (see 
also inlinedefs). 

fontdefs (alfont) Display Package 

Defines a uniform interface for all font formats. It includes facilities for dynamically swapping 
font files. 

framedefs (nonresident, swapper) Modules 

Provides low level operations on modules and their runtime representation (global frames). It 
includes facilities for controlling residency of a module's code segment. 
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fspdefs (FSP) Storage Management 

This memory allocation package provides temporary storage for small, transient data structures 
whose size is not known at compile time. 

imagedefs (MAKEIMAGE) Image Files 

Image files are used to save the state of a computation so that it can be restarted later (perhaps in 
a different environment). Different types of image files can be created using the procedures 
defined in this interface; each type makes different assumptions about the state of the 
environment when it is restarted. 

inlinedefs (inlinedefs) Miscellaneous 

Defines a set of instructions not accessible at the language level. Logical operations and some 
extended precision arithmetic is included (see also doubledefs). 

iodefs (STREAMiO) StreamlO Package 

A simple Teletype style I/O interface is provided by these procedures. Minimal editing and 
input and output conversion routines are included. 

keydefs (keyboard, keystreams) Keyboard Package 

Provides device-dependent operations for the keyboard, keyset, and mouse. Simple operations 
are implemented using the standard stream interface (see streamdefs). 

LOADERDEFS (LOADER) Modules 

Contains a procedure for unloading a configuration from a running Mesa system, in a way that it 
can be optionally loaded again later. 

miscdefs (miscellaneous) Miscellaneous 

A set of miscellaneous but useful procedures that don't obviously belong in any of the other 
interfaces. 

mopcodes (Hardware) OIS Processor Principles of Operation 

Defines the opcode numbers used by the Mesa instruction set It is useful when inline procedures 
need to be defined to obtain access to machine facilities not available in the language. 

OSSTATICDEFS (BCPL) Alto Operating System Reference Manual 

Defines information available through the Alto Operating System Swat resident. 

processdefs (process) Processes and Monitors 

Includes a number of extensions to the language facilities for processes, monitors, and condition 
variables. Priorities and timeouts can be adjusted, and processes can be detached and aborted. 

realdefs (not implemented) Miscellaneous 

Defines the procedure calls generated by the compiler for operating on real data types. (Mesa 
does not provide an implementation of this interface.) 
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segmentdefs (segments, files, swapper) Segment and File Packages 

Operations on data and file segments are contained here; this includes virtual memory 
management and swapping. Basic operations on files and their attributes are also included. 

streamdefs (display, keystreams, streams) Disk, Display, Keyboard, and Streams Packages 

Defines the operations common to all streams. It also includes some device-dependent 
operations unique to the disk, keyboard, and display. 

stringdefs (strings) String Package 

A utility package for copying, comparing, and converting strings and substrings. 
systemdefs (fsp, segments) Storage Management 

Provides a simplified interface to the segment and free storage package for allocating and 
releasing temporary storage. 

timedefs (Timeconvert) Time Package 

Includes a number of procedures for converting between internal (32 bit GMT), intermediate 
(unpacked record) and external (string) time formats. 

TRAPDEFS (RESIDENT, NONRESIDENT) Traps 

Defines the runtime implementation of traps generated by the hardware and software. 
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3. System Organization 



Mesa systems are available in both standard and basic configurations. The former is intended 
for the day to day operation of most program developers, who do not want to provide a large 
amount of software in order to perform simple tasks. On the other hand, the basic system is 
intended for clients who are building complete applications from the ground up, and wish to 
replace many of the standard facilities their own versions. Several optional packages are 
available for augmenting the capabilities of the the standard and basic systems in various 
directions, and we hope that many more will be added. 



Standard System 

Except for the optional packages listed below, the standard Mesa system (mesa.image) includes all 
the facilities described in this document. In addition to the interfaces described in the previous 
section, it includes a simple user interface called the Mesa Executive; the commands it accepts 
are described in Section 4. 



Basic System 

The basic system (basicmesa.image) includes the following facilities: runtime support for the 
language: signaller, resident, nonresident; modules used to access files on the disk: segments, 
files, swapper, diskio, diskkd, bfs, streams, directory; the process package (process), the string 
package (strings), and the free storage package (fsp); the loader and its associated modules; a 
debugger interface; and a nub of the Mesa Executive. The are no facilities for using the display 
or keyboard in the basic system, nor are there any of the modules associated with making image 
files. These and other packages are available as separate configurations (see below). 



Optional Packages 

To assist in tailoring applications built using the basic system, some facilities are optional and 
packaged separately. The configurations marked as standard are included in the standard Mesa 
system; the others may be loaded optionally. None of these packages are part of the basic system; 
they must be included in the user's configuration (or otherwise loaded) if they are needed. 



checkpoint 

Implements check files (Image Files). 

DISPLAYPACKAGE (STANDARD) 

Implements the display and font procedures. 
Package). 



An instance of streamjo is also included (Display 
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1MAGEMAKER (STANDARD) 

Implements image files (Image Files). 

IMAGERUNNER 

Implements image file loading (Image Files). 

UNNEWCONRG 

Implements unloading of configurations (Modules). 

WINDOWPACKAGE 

Implements rectangles, display streams, fonts, windows, menus, and selections. An instance of 
streamio is also included. This package is no longer supported (Window Package). 
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4. Mesa Executive 



The Mesa Executive serves as the user interface for the standard Mesa system. It provides 
facilities for loading and starting Mesa programs, and for saving the state of a system in an 
image file; it is also the primary interface between your program and the Mesa debugger. The 
Mesa Executive has five commands, each identified by their first letter: New, Start, Debug, 
Makelmage, and Quit. The commands are discussed in detail below. 

New [filename] 

Performs a new on the configuration (or module) filename, loading it into the system. If 
no extension is supplied, ".bed" is assumed. The global frame of the control module of 
the configuration is returned, but it is not started. If the configuration contains no 
control module, zero is returned. 

Start [frame] 

Performs a start on frame (specified in octal). Note that module parameters can not be 
supplied. Typing esc in place of frame starts the frame returned by the last New 
command. 

Debug [confirm] 

Invokes the Mesa Debugger. Typing tswAT at any point during execution of a Mesa 
program also invokes the Debugger. In addition, t shift- swat attempts to invoke Swat. 

Makelmage [filename] 

Saves the current state of the system (including any programs that have been loaded) on 
the image file filename. If no extension is supplied, ". image" is assumed. The section 
on Image Files contains further details on the Makelmage command. 

Quit [confirm] 

Exits the Mesa environment, cleaning up its state, and returns to the Alto Executive. 
Typing shift-swat at any point during execution also attempts to abort the computation 
and return to the Alto Executive. 

The Mesa Executive keeps a typescript of these commands (and all data sent to the standard 
output stream) on the file mesa.typescript; it can be used as a log of your Mesa session. 

Most of the above commands can be specified on the command line used to invoke Mesa (and 
some are valid for BasicMesa, as well). See the Mesa User's Handbook for further details. 
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5. System Facilities 

The material which follows is divided into several subsections, each of which describes a more or 
less logically disjoint subset of the system. The subsections are listed below, and follow this 
section in alphabetical order. The relevant definitions modules, which clients will want to 
reference, are named in parentheses below, as well as in the subsections which follow. 

Directory Package (Directorydefs) 

Disk Streams Package (STREAMDEFS) 

Display Package (displaydefs, fontdefs, streamdefs) 

File Package (altodefs, altofiledefs, segmentdefs) 

Image Files (imagedefs) 

Keyboard Package (KEYDEFS, streamdefs) 

Miscellaneous (doubledefs, inlinedefs, miscdefs) 

Modules (framedefs, loaderdefs) 

Processes and Monitors (PROCESSDEFS) 

Segment Package (allocdefs, segmentdefs) 

Storage Management (fspdefs, systemdefs) 

StreamlO Package (iodefs) 

Streams (streamdefs) 

String Package (altodefs, stringdefS) 

Time Package (TiMEDEFS) 

Traps (TRAPDEFS) 

Window Package (menudefs, rectangledefs, windowdefs) 
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Alto/Mesa Directory Package 

May 1978 



The Mesa directory package provides a number of procedures to manipulate the Alto directory 
(SysDir). (See directorydefs.) Currently, these routines do not support either sub -directories or 
file version numbers. This section depends heavily on the section on Files, and that section 
should be read before this. (See Alto Operating System Reference Manual for file structure 
details.) 

The simplest operation provided is to enumerate all of the file entries in the directory: 

EnumerateDirectory: procedure [proc: procedure [pointer to FP, string] returns [boolean]]; 

Calls proc once for each filename in the directory, passing it pointers to the file's FP and 
name. Processing terminates when proc returns true or the end of the directory is 
reached. 

Fine point: these parameters are local to the enumeration procedure and must be copied if they are to be 
retained after the enumeration completes. 

The following procedures may be of use to programmers implementing features beyond those 
provided by NewFile and DestroyFile. 

Directory Lookup: procedure [fp: pointer to FP, name: string, create: boolean] 
returns [old: boolean]; 

Looks up name in the directory. If an entry already exists, its file pointer is copied into 
fp and true is returned, otherwise false is returned. In addition, if create is true, the file 
will be created (with one empty data page), and the new file pointer will be copied into 
fp. 

DirectoryLookupFP: procedure [fp: pointer to FP, name: string] returns [old: boolean]; 

Similar to DirectoryLookup, except that the directory is searched for a matching FP, It 
returns true if the file pointer was found. In addition it will supply the filename if 
name is not nil, 

DirectoryPurge: procedure [fp: pointer to FP, name: string] returns [found: boolean]; 

Removes the entry corresponding to name from the directory (it does not disturb the file 
pages pointed to by the FP, however). If the file is found, its file pointer is copied into 
fp and true is returned, otherwise false is returned. 

DirectoryPurgeFP: procedure [fp: pointer to FP] returns [found: boolean]; 

Similar to DirectoryPurge, except that the directory is searched for a matching FP. It 
returns true if the file pointer was found, deleting the entry in the process. Perhaps it 
should also copy the file's name into a supplied parameter? 
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Alto/Mesa Disk Streams Package 

May 1978 



A disk stream (see streamdefs) is an array-like representation of a disk file. Parts of the file 
may reside in memory from time to time at the convenience of the stream. Like most arrays, a 
stream has a length; unlike array variables, the length of a stream may be changed by appending 
to it, and the maximum length is very large. Disk streams are created by the procedures: 

NewByteStream, NewWordStream: procedure [name: string, access: AccessOptions] 
returns [DiskHandle]; 

A FileHandle for the file name is created with the given access and DefauItVersion. It is locked 
and opened, and a byte or word stream is attached to it. If access is Append only, the stream is 
positioned at the end of the file, otherwise at the beginning. If access is DefaultAccess, Read is 
assumed. If a valid FileHandle already exists, a stream may be attached to it by calling the 
procedures: 

CreateByteStream, CreateWordStream: procedure [file: FileHandle, access: AccessOptions] 
returns [DiskHandle]; 

The streams FileHandle and access may be read directly from the StreamObject (after 
discrimination) using the field names file and read, write, append. 

The operations allowed on the stream's length are determined by its access options; these options 
are negotiated with the underlying file system (see the section on Files). The options supported 
by the stream package are: 

Read: the length is a constant 
Write: the length may decrease. 
Append: the length may increase. 

A disk stream has as part of its state a current index into the array representation of the file. 
The first data item is at index zero, the last at length- 1. An invariant of a disk stream is index 
<= length. The current index and length are used in defining the semantics of the standard 
operations on disk streams, which are as follows: 

reset[s] 

Effect: sets the index to zero. 

get[s] 

If: read and index < length. 

Effect: t «- s[index]; index «- index+1; RETURN[t]. 
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putback[s, i] 

Effect: StreamOperation error. 
put[s, i] 

If: (write and index < length) or 

(append and index = length). 
Effect: spndex] <- i; index <- index* 1; length «- MAx[index, length]. 

endof[s] 

Effect: return [index = length]. 

destroy[s] 

Effect: if '-read and index # 0 then length <- index (i.e. truncate the file if it is not 
positioned at the beginning). Release the FileHandle if there are no segments attached to 
it. 

If it is necessary to truncate a file in the cases not covered by destroy (i.e. read or index = 0), 
call 

TruncateDiskStream: procedure [stream: StreamHandle]; 

Effect: length «- index; stream.destroy[stream]. 

Actually, there is a little more to it. Disk streams deliver either byte or word items; in either 
case, the index is always computed in bytes. So the description above is a simplification of what 
really happens. Rather than clutter it up, suffice it to say that when accessing files in word 
mode, index values are always rounded up to word boundaries. 

In addition to the standard operations, the following disk dependent functions are provided to 
efficiently copy large blocks of words to or from the stream: 

ReadBlock: procedure [stream: StreamHandle, address: pointer, words: cardinal] 
returns [count: cardinal]; 

If: read. 

Effect: count «- MiN[words,length-index]; 
for index in [index.. index+count) DO 
MEMORY[address] «- streampndex]; 
address «- address* 1; 

ENDLOOP. 

WriteBlock: procedure [stream: StreamHandle, address: pointer, words: cardinal] 
returns [count: cardinal]; 

If: (write and index < length) or 

(append and index = length). 
Effect: count «- if append 
then words 

else MiN[words,length-index]; 
for index in [index.. index+count) do 
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stream [index] «- MEMORY[address]; 
address «- address* 1; 

ENDLOOP. 

length «- MAx[index, length]. 

When using ReadBlock and WriteBlock, the initial index must be on a word boundary (otherwise 
the StreamPosition error results). Note that the returned value may be less than words if the 
stream's access does not allow reading or writing of the whole block (the StreamAccess error is 
never raised by either of these procedures). 

The stream index alluded to above is actually a structure: 

Streamlndex: type = record [ 
page: PageNumber, 
byte: cardinal]; 

The first data byte of a stream is at Streamlndex[0, 0]. The current stream position can be 
determined by calling 

Getlndex: procedure [stream: StreamHandle] returns [Streamlndex]; 

It is quite acceptable to do double precision arithmetic on a Streamlndex (and even single 
precision operations on the individual fields, if you are careful about borrows, carries, and 
overflows). Note, however that a Streamlndex is not compatible with the double precision 
arithmetic of long integers. The paged structure of the index can be restored by invoking 

Normaiizelndex: procedure [index: Streamlndex] returns [Streamlndex]; 

It returns an index whose byte field is in the range [O..CharsPerPage). An index may be 
modified by calling 

Modifylndex: procedure [index: Streamlndex, change: integer] returns [Streamlndex]; 

The current index may be set by calling 

Setlndex: procedure [stream: StreamHandle, index: Streamlndex]; 

Note that this may actually extend the file (with unspecified data) if Append access is allowed. 
To determine if this will happen, you might first want to call 

FileLength: procedure [stream: StreamHandle] returns [Streamlndex]; 

Note that FileLength sets the stream to the end-of -file and returns the length as seen through the 
stream; this may differ from the physical length of the disk file (if, for example, items have been 
appended to the stream but not yet written to the disk). 

You may test for the greater-than relation between two stream indexes by calling the procedures 
GrEquallndex: procedure [i1, i2: Streamlndex] returns [boolean]; 
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Grlndex: procedure [11, i2: Streamlndex] returns [boolean]; 

If a physical disk location is required along with the stream position, a file address (FA) will 
prove useful (see altofiledefs); it is similar to a Streamlndex with a disk address (DA) tacked on 
the front, except that the page field is one origin (in the Alto file system, page zero is the leader 
page). 

FA: TYPE a MACHINE DEPENDENT RECORD [ 

da: DA, 

page: PageNumber, 
byte: cardinal]; 

You may record the current stream position and re-establish it later, in a fashion similar to 
Getlndex and Setlndex, by calling the procedures 

GetFA: procedure [stream: StreamHandle, fa: pointer to FA]; 

JumpToFA: procedure [stream: StreamHandle, fa: pointer to FA]; 

The special thing about JumpToFA is that the disk address in the fa is taken as a hint; if it 
doesn't work out (the page number or file serial number doesn't match the stream's version of 
them), JumpToFA will attempt to find the requested page via the shortest route and correct the fa 
accordingly. This may involve starting over at the beginning of the file. If that fails, 

InvalidFP: signal [fp: pointer to FP]; 

will result, probably indicating that the file has been moved (or worse, deleted!) since the stream 
was attached to it. A call on some directory searching procedure may prove useful in this 
situation, to determine if retrying the operation (with a new fp) is appropriate. 
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Alto/Mesa Display Package 

May 1978 



The Mesa Display Package provides a simple, Teletype style interface to the display. There is 
provision for using any available font; however the display is restricted to a single font for any 
particular incarnation. The font operations (described at the end of this document) are 
independent of the display implementation and may be used by any other display package. The 
package will optionally maintain a typescript of displayed output. 



Display Stream 

Normal access to the display is through a stream interface (see the section on Streams). There is 
no provision for multiple display streams. The module systemdisplay implements the following 
procedures defined in streamdefs: 

GetDefaultDisplay Stream: procedure returns [DisplayHandle]; 

The interpretation of the basic stream operations is: 

reset clears the display and resets the typescript, 
put displays the character at the next sequential location, 
get, putback and destroy signal StreamError[StreamAccess]. 
endof returns false. 

ClearCurrentLine: procedure [StreamHandle]; 

The current line of the display is cleared. The next character will be displayed at the left 
margin. The typescript is repositioned to the beginning of the line. 

ClearDisplayChar: procedure [stream: StreamHandle, char: character]; 

Erases the last character written on the display. The character must be supplied since the 
stream retains no knowledge of what characters are displayed (the typescript is optional). 

displaydefs defines some additional interface procedures: 

InitDisplay: procedure [dummySize, textLines, nPages: cardinal, f: FontDefs.FontHandle]; 

This procedure initializes the display with dummySize blank scan lines at the top and 
room for at most textLines lines of text using nPages pages of memory for data 
structures and bitmap. The number of text lines and the display width are reduced if 
necessary to make everything fit in nPages. 

FinePoint: the amount of memory necessary to guarantee that n full width lines of text can be displayed is 
n*(4+h*w) words, where h is the height of the font in scan lines (rounded up to an even number) and w is 
the width of the display in words. 
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SetSystemDisplaySize: procedure [nTextLines, nPages: cardinal]; 

Clears the display and reinitializes it with the new parameters. 

Set Sy st emDisplay Width: procedure [indent, width: cardinal]; 

Clears the display and reinitializes it with the new width parameters, indent is the 
number of bits from the left edge of the screen to the first display position and width is 
the width of a display line in bits. (The actual width will be the nearest multiple of 32 
bits.). 

FinePoint: indenting by multiples of 16 bits is very efficient. 
SetDummyDisplaySize: procedure [nScanLines: cardinal]; 

Changes the size of the blank space at the top of the display. 
Background: type = {white, black}; 
DisplayOff: procedure [color: Background]; 
DisplayOn: procedure; 

DisplayOff releases all of the space allocated to the display and swaps out the font All of 
the parameters of the display are saved so that DisplayOn can restore the previous state 
(but not the contents) of the display. 

BlinkCursor: procedure returns [boolean]; 

Blinks a "cursor" at the position where the next character will be displayed. Each call 
changes the state of the cursor from "on" to "off" or vice versa. BlinkCursor returns true 
if the last call changed the cursor state to on. The cursor is always turned off before a 
character is displayed or erased. 

SetTypescript: procedure [StreamDefs.DiskHandle]; 

This procedure establishes a disk stream as a typescript for the display. Passing nil will 
disable the typescript Characters sent to the display stream while the display is off will 
appear in the typescript. The typescript must be an open byte stream with 
Read+Write+Append access. 

DisplayControl: program; 

This is the control module used in Mesa.image. It will initialize the display, font and 
typescript (using either MesaFontal or SysFont.al and Mesa.Typescript) and start a 
process to call BlinkCursor at half second intervals. It will also reestablish the display 
(including font and typescript) after a Makelmage or MakeCheckPoint. 



Alto/Mesa Display Package 



17 



Fonts 

A FontObject provides a simple object style interface to character fonts. Operations are provided 
for painting or erasing characters from the font in a bitmap, fontdefs defines the following 
types and procedures: 

BitmapState: type = record [ 
origin: pointer, 

wordsPerLine, x, y: [0.. 7777 7b)]; 

A BitmapState describes where a character will be placed within a bitmap, origin is a 
pointer to the beginning of the bitmap. wordsPerLine is the horizontal width of the 
bitmap (it must be even if the bitmap is to be displayed), x and y are measured from the 
upper left corner in bits right and scan lines down respectively. 

FontHandle: type = pointer to FontObject; 

FontObject: type = record [ 

paintChar: procedure [FontHandle, character, pointer to BitmapState], 
clearChar: procedure [FontHandle, character, pointer to BitmapState], 
charWidth: procedure [FontHandle, character] returns [cardinal], 
charHeight: procedure [FontHandle, character] returns [cardinal], 
close: procedure [FontHandle], 
destroy: procedure [FontHandle], 
lock: procedure [FontHandle] returns [pointer], 
unlock: procedure [FontHandJe]]; 

A FontObject implements the following operations: 

paintChar: ORs the specified character from the font into the bitmap position specified in 
the BitmapState; x is updated to point to the next character position. There is no bounds 
checking. 

clearChar: erases the bit rectangle which bounds the character. The input state points just 
beyond the character and is modified to point to where the character used to be. 
paintChar [f, c, s] followed by clearChar[f, c, s] leaves s unchanged. 

charWidth, charHeight: return the width and height of a character in bits and scan lines 
respectively. 

close: swaps the font out of memory if it is not otherwise in use. The font will always be 
swapped in when needed. It is not generally locked. 

destroy: calls close and then releases the space allocated for the FontObject. The font 
segment is not deleted. 

lock: locks the font segment in memory and returns a pointer to the first word. This can 
be used to implement other operations on the bits in the font. Note that nothing in a 
FontObject dictates what font format is used. 

unlock: unlocks the font after a call to lock. j 
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CharWidth: procedure [font: FontHandle, char: character] returns [cardinal]; 

Equivalent to font.charWidth[font, char], 
CharHeight: procedure [font: FontHandle, char: character] returns [cardinal]; 

Equivalent to font.charHeight[font, char]. 

CreateFont: procedure [SegmentDefs.FileSegmentHandle] returns [FontHandle]; 

Allocates space (from the system heap) for a FontObject and initializes its operations to 
use the font in the supplied segment 

The module AtFONT implements FontObjects for "Al" format fonts. Modules for other font 
formats can be substituted easily. At this time no other modules have been written or planned. 

Mesa.image uses systemdisplay, alfont, and displaycontrol for its default display. They are 
also available as a separate package in displaypackage for users of BasicMesa. displaypackage 
also contains an instance of streamio. 
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Alto/Mesa File Package 

May 1978 



Logically, the Mesa file package is a sub-module of the segmentation machinery, but it is 
described separately because other objects (e.g. disk streams) also use this interface. Internally, 
the file machinery maintains a set of items called FileObjects: a file object, among other things, 
contains the file's disk address and serial number, as well as its access rights, several reference 
counts, and an optional file length hint. 

The Mesa system follows most conventions of the Alto file system (although some, including 
multiple versions and sub-directories are not currently supported.) See the Alto Operating 
System Reference Manual document for a description of the Alto file system. A description of 
the various procedures used to manipulate the Alto's directory appears in the section on 
Directories. 



Files 

A file is an integral number of pages which logically appear to be contiguous, irrespective of 
their physical location. The pages of a file are numbered from zero up to some maximum (see 

ALTODEFS): 

MaxFilePage: cardinal; — maximum file page number 
PageNumber: type = [0.. MaxFilePage]; 

In the Alto file system, page zero of the file (the leader page) is special; it contains file status 
information. Thus the data actually begins at page one. 

Externally, a file is known by its name, which is just a string. Internally, Mesa retains only a 
file's FP, which is an abbreviated form of the Alto file system's file pointer (see altofiledefs): 

FP: TYPE = RECORD [ 

serial: SN, — internal file serial number 

leaderDA: vDA]; — first virtual disk address 

The correspondence between file names and FPs is maintained in the file system's directory 
(SysDir). After the file is initially looked up, the name is discarded; the Mesa world deals only 
in FPs thereafter. A directory search is required if the name must be recovered. 



File Objects 

A FileHandle is used to refer to a file in the Mesa environment, and can be obtained by a call on 
NewFile (described bedow); it is simply a pointer to a record called a FileObject (see 

SEGMENTDEFS). 
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FileHandle: type = pointer to FileObject; 



FileObject: type = record [ 
open: boolean, 
read, write, append: boolean, 
lock: [O..MaxLocks], 
segcount: [O..MaxSegs], 
swapcount: [C.MaxRefs], 

. . . ]; 



— reference count 

— attached segments 

— swapped in segments 

— plus other private fields 



— access rights 



if the file is open 



The following options are used when creating new file objects: 

AccessOptions: type = [0..7]; 
Read: AccessOptions =1; 
Write: AccessOptions = 2; 
Append: AccessOptions = 4; 

VersionOptions: type = [0..3]; 

NewFileOnly: VersionOptions = 1; 
OldFileOnly: VersionOptions = 2; 

Read access allows existing pages of the file to be read; Write means that existing pages can be 
written (or deleted; perhaps a separate Delete option should be included). Append allows new 
pages to be added to the end of the file (files do not have holes in them). 

Fine point: Append does not imply Write access. Append means that new pages may be added to the file but existing 
pages may not be modified. 

Disallowed combinations are {NewFileOnly, OldFileOnly} and {NewFileOnly, -Append}. If 
Append access is not specified, OldFileOnly is assumed. If you like, you may specify 
DefaultAccess, which is equivalent to Read. (Note that Append access must be specified in order 
to create the file.) 

Fine point: if DefaultVerslon is specified, the file is created if it did not previously exist. 



Signals associated with FileObjects are as follows: 

FileNameError: signal [name: string]; 

The file name is invalid, or the file does not exist (OldFileOnly), or the file does exist 
(NewFileOnly). 

FileAccessError: signal [file: FileHandle]; 

An attempt to perform some operation not allowed by the current access, or the requested 
access and version options are inconsistent (see the disallowed combinations above). 



Signals 
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InvalidFP: signal [fp: pointer to FP]; 

A file positioning operation has determined that the file serial number in the FP of the 
file object does not match the disk label. Most likely, the FileHandle references a file 
which has been moved or destroyed (or clobbered) since it was last referenced 

FileError: signal [file: FileHandle]; — all other file errors 



File Creation/Deletion 
A FileObject is created using the following procedures: 

NewFile: procedure [name: string, access: AccessOptions, version: VersionOptions] 
returns [FileHandle]; 

Given a file name and access rights, this procedure creates a new file object and returns a 
pointer to it. A check is made that the file exists in the directory, creating it if necessary, 
but the file is not opened as a result of this call. Objects attached to the file (segments 
and streams, for example) ensure that the file is open before attempting a transfer. If 
there is already a file object for the file specified, its access is updated (by or'ing; this is 
not a protection system), and a pointer to the existing object is returned. 

InsertFile: procedure [fp: pointer to FP, access: AccessOptions] returns [FileHandle]; 

Creates a file object directly from fp, without searching the directory. If there is already 
a file object with a matching fp, its access is updated (by or'ing; this is not a protection 
system), and a pointer to the existing object is returned. 

Internally, Mesa keeps track of the number of segments attached to each file (segcount) and of 
those the number which are currently swapped in (swapcount). When the swapcount goes to 
zero, the file may be closed, and when the segcount goes to zero, the file object is released (only 
the latter operation happens automatically). Since a file may have other objects attached to it 
(streams, for example), it may be necessary to prevent the file object from being released even 
when there are no more segments attached to it. The lock field serves this purpose, and is 
manipulated by the procedures 

LockFile, UnlockFile: procedure [file: FileHandle]; 

A maximum of MaxLocks locks may be performed on each file object. Note that a file object is 
not automatically released when its lock count goes to zero. 

A FileObject is released by 

ReleaseFile: procedure [file: FileHandle]; 

The file is first closed if it is open; then its file object is released. A FileError will be 
generated if there are segments associated with the file at the time of this call. Note: 
except for this error check, releasing a file which is locked is a no-op. 

A file is physically destroyed by calling 
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DestroyFile: procedure [file: FileHandle]; 

In addition to releasing the file object, the file's pages are deleted and its entry is removed 
from the directory. The file object must not have any segments currently attached to it, 
nor may it be locked; either condition results in a FileError. 

To be on the safe side, destroying a file is somewhat complicated if it currently has segments 
attached to it. The file must first be locked, then all of its segments deleted and all streams 
attached to it destroyed, then the file should be unlocked and finally DestroyFile should be called. 
This sequence assumes that no other client has a lock on the file. 



File Properties 

Characteristics of the disk file associated with a FileObject are obtained and changed using the 
following procedures: 

FindFile: procedure [fp: pointer to FP] returns [FileHandle]; 

Searches all existing file objects for one whose serial number and disk address match 
those contained in fp. Returns nil if no match can be found. 

GetFileFP: procedure [file: FileHandle, fp: pointer to FP]; 

Copies. the file pointer from file into fp. 

GetFileAccess: procedure [file: FileHandle] returns [access: AccessOptions]; 

Converts the read, write, and append bits of a file object into a form that can be passed 
to NewFile. 

SetFileAccess: procedure [file: FileHandle, access: AccessOptions]; 

Or's access into the file object (this is not a protection system). 

File lengths hints are no longer contained in every FileObject. A separate object contains the 
length for a file. This separate length object is not required and is allocated only when 
operations on file lengths are invoked (see segmentdefs). Operations on file lengths are: 

GetEndOfFile: procedure [file: FileHandle] returns [page: PageNumber, byte: cardinal]; 

Returns the page number of the last page in the file that contains data, together with the 
number of bytes in that page (the number of the first non-existent byte in the page, 
counting from zero). In the Alto file system, page zero is the leader page, the first data 
page being page one. Note that if the last data page is full, a null page is appended to the 
file, but GetEndOfFile does not tell you about it (so do not count on it being there). For 
an empty file, this routine returns [0, BytesPerPage] (reflecting the existence of the 
leader page). 

GetEndOfFile first opens the file (if it is closed) to obtain the length hint from the leader page. 
It also inserts the current file length into the file length object (creating one if necessary), so that 
subsequent requests for the length will not require reading the disk. 
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SetEndOfFile: procedure [file: FileHandle, page: PageNumber, byte: cardinal]; 

Extends or truncates the file as necessary to make page the number of its last data page, 
with byte bytes in it. The arguments are first adjusted to include a null page if byte = 
BytesPerPage. Extending requires Append access, truncating requires Write access. 



Miscellaneous 

The procedure EnumerateFiles is provided so that one may conveniently scan all file objects that 
currently exist. 

EnumerateFiles: procedure [proc: procedure [FileHandle] returns [boolean]] 
returns [file: FileHandle]; 

This procedure calls proc once for each file object that is currently exists. This process 
will terminate when the list of file objects is exhausted or when proc returns true. In the 
latter case, the FileHandle of the last FileObject processed is returned. Otherwise, nil is 
returned. 

If new file objects are created while EnumerateFiles is in control, it is not guaranteed that they 
will be included in the sequence of FileHandles passed to proc. 
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Alto/Mesa Image Files 

May 1978 



A Mesa image file contains the information necessary to start execution of a Mesa system. In 
addition to image files that contain all code and data, there are also image files, called check 
files, that contain only data. (Check files know the addresses of other files on the disk and 
therefore cannot be moved like other image files). This section defines the format of image files 
and the facilities provided to make them. See imagedefs for further details. 

The format of an image file is as follows: 

ImageHeader: type = machine dependent record [ 
prefix: ImagePrefix, 
map: array [0..0) of Mapltem]; 

ImagePrefix: type = machine dependent record [ 

versionident: cardinal, — should be ImageDefs.VersionlD 

version, creator: BcdDefs.VersionStamp, 

options: word, — should be 0 

leaderDA: AltoFileDefs.vDA, 

state: StateVector, 

type: ImageType, 

• • .]; 

ImageType: type = {bootmesa, makeimage, checkfile, other}; 

Mapltem: type = machine dependent record [ 
page: [0..255], 
count: [0..127], 
body: select tag:* from 
normal => null, 
change => [ 

da: DiskDefs.DA, 
base: cardinal], 
endcase]; 

The first data page of an image file is a record of type ImageHeader. The size of the array 
depends on the number of page groups in the file. The last element of the array is 
Mapltem[0,0,normal[]]. The versionident field identifies the version of the format being used 
and must match the value of Versionld in ImageDefs. The version field identifies the date and 
machine on which the image file was made. The creator field identifies the image file that was 
built upon to produce the current image file. The options field specifies other data about the 
image file as a bit mask. Currently no options are supported. The leaderDA is valid only for 
check files; it is the disk address of the leader page of the image file and is used to make sure the 
file is not moved. The StateVector in state is the initial state of the program. This StateVector 
will be loaded as the lowest priority process and will be started using the Mesa transfer with 
construct. 

After the first page, the remaining pages of the file contain the pages to be loaded into memory. 
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The normal entries in the map array identify the core locations and number of pages in each page 
group. The change entries in the map array also indicate a change in the file from which the 
page group is read. The runmesa.run program which loads an image file will load page groups 
until it encounters a null Mapltem. 



Making Image Files 

The basic system contains code to make an image file of itself and any user programs which have 
been loaded. Clients may make an image file by calling the procedure: 

Makelmage: procedure [name: string] ; 

Make an image file on file name. Returns to Alto Executive. When the image file is, 
restarted, Makelmage returns to its caller. 

Clients may also make an image file by invoking the Mesa Executive's Makelmage command. It 
accepts a filename, defaults the extension to ".image" and calls Makelmage [name]. When the 
image file is restarted, the Mesa Executive will be ready to accept a new command. 

Makelmage normally merges all the BCDs that have been loaded into one bed, and cleans up 
system data structures. This results in faster loading of additional BCDs into the new image. 

Those clients that do not want BCDs merged during a Makelmage because they call UnNewConfig 
may use the following procedure: 

MakeUnMergedlmage: procedure [name: string]; 

Signals that may be generated by Makelmage or MakeUnMergedlmage are: 
Invalidlmage: signal; 

An attempt has been made to make an image file on top of the currently excuting image 
file. 

NoRoomlnlmageMap: signal; 

The map in the ImageHeader has filled up. This usually means that there are too many 
segments in memory at the time the image file is made. 



Check Files 

Check files differ from normal image files in that they do not contain all the code and data to 
start the execution of the image file. Check files only contain the data of the Mesa system, and 
all code and other segments remain in their original files. As a result, check files are made and 
restarted very quickly. However, care must be taken not to destroy files that are pointed to by 
the check file. Check files are useful for making check points in the execution of a Mesa system. 
The procedures and signals that make check files are: 
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MakeCheckPoint: procedure [name: string]; 

Makes a check file on file name. Returns to caller when finished as if nothing happened. 
Upon restart again returns to caller. 

NoRoomlnCheckMap: SIGNAL; 

In MakeCheckPoint, the map in the ImageHeader has filled up. This usually means that 
there are too many segments in memory at the time the check file is made. 

The ability to make check files is not included in the basic system. Clients should include the 
checkpoint module in their configuration. 

Running Image Files 

Mesa programs may run another image file without returning to the Alto Executive. The 
procedures and signals that implement this are: 

Runlmage: procedure [file: SegmentDefs.FileSegmentHandle]; 

Runs the image file specified by file where file is a segment handle for the header of the 
image file. The current state of the present image file is lost, and the new image file is 
loaded and started. 

Fine point: currently the header of an image file is page one (this may change in the future, and may not be 
constant). Communication between the two image files must be done via disk files (like Com.cm). See the 
Alto Operating System Reference Manual. 

Invalidlmage: signal; 

In Runlmage, file specifies an invalid image file. 

NoRoomForLoader: signal; 

In Runlmage, there is no room for the bootstrap loader that loads and starts the image 
file. 

Clients should include the configuration imagerunner in their configuration. 

Miscellaneous 

The version stamp of the currently running image file may be obtained by calling the procedure: 
ImageVersion: procedure returns [BcdDefs.VersionStamp]; 

A client may stop execution of a Mesa system and return to the Alto Executive by calling: 
StopMesa: procedure; 

A client may terminate execution of a Mesa system as if shift-swat had been typed and return to 
the Alto Executive by calling: 



Alto/Mesa Image Files 



27 



AbortMesa: procedure; 



Makelmage Restrictions 

1. The name of the new image file may not be the same as the name of the image file running at 
the time Makelmage is called. An image file can be renamed any time it is not running. 

2. The user program should not have handles on any files or disk streams. Any file segments 
allocated by a user program will be made a part of the new image file. 

3. This list of restrictions may not be exhaustive. In general you should avoid doing anything 
other than loading modules and initializing data structures before making an image file. 



MakeCheckPoint Restrictions 

1. The name of the new image file may be the same as the name of the image file running at the 
time MakeCheckPoint is called, only if the current image file is a check file. A check file 
should not be renamed. 

2. The files that are pointed to by the check files should not be moved or altered. Care must be 
taken with open disk streams that the pages of the current position of the stream are not moved 
or destroyed. 

3. This list of restrictions may not be exhaustive and care must be taken with all files that are 
open at the time the check file was make. 
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The Keyboard package consists of the modules keystreams and keyboard and provides a 
Teletype style interface to the undecoded keyboard through a device independent stream 
interface. Multiple, independent keyboard streams are supported. A default keyboard stream is 
created at initialization time. (See the section on StreamlO for higher level operations.) The 
Keyboard Package also optionally causes the hardware cursor to track the mouse. A single 
keyboard process runs at interrupt level approximately 60 times per second to sample the 
keyboard hardware. 

The following procedures and types are defined in streamdefs. 
KeyboardHandle: type = pointer to Keyboard StreamObject; 

The standard operations on a keyboard stream are: 

reset[s] clears the buffer associated with s; any characters in the buffer are lost. 
get[s] . returns the next character in the buffer; if endof[s] is true, waits until it is 

FALSE. 

putback[s,i] modifies the stream so that the next get[s] will return i, independent of 
any type-ahead. If the buffer is full, putback is a no-op (sorry about that). 

put[s,i] produces a StreamAccess error. 

endof[s] true if there are no characters in the buffer. 

destroy [s] destroys s in an orderly way, freeing the space it occupies. Any characters in 
the buffer at the time of the destroy are lost. If s is the current keystream, the 
StreamOperation error results. 

CreateKeyStream: procedure returns [KeyboardHandle]; 

Creates a new keyboard streams. Any number of streams may be created. Each stream 
has its own buffer for type ahead. (Space for the StreamObject is allocated from the 
system heap.) 

GetDefaultKey: procedure returns [KeyboardHandle]; 

Returns the default stream (created at initialization time). 

GetCurrentKey: procedure returns [KeyboardHandle]; 



Returns the current stream. Initially the default keyboard stream is current. 
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OpenKeyStream: procedure [stream: StreamHandle]; 

Makes stream the current keyboard stream.The stream which was current before the call 
is undisturbed, except that input characters are no longer directed to it by the keyboard 
process, but to stream instead. 

CloseKey Stream: procedure [stream: StreamHandle]; 

Makes the default keyboard stream current. Characters already typed remain in stream's 
buffer. The StreamOperation error results if stream is not the current stream. 

CursorTrack: procedure [boolean]; 

Calling this procedure with true enables cursor tracking; false disables it. When tracking 
is enabled, the mouse coordinates are copied to the cursor coordinates each time the 
keyboard process runs. 



Low Level Access 



The basic system does not provide access to the keyset or mouse through the stream. Definitions 
are provided for clients wishing to access the bits of the keyboard directly or to change the 
interpretation of any of the keys. The module keydefs defines types and procedures for lower 
level access to the keyboard hardware. 

updown: type = {down, up}; 

KeyBits: type = machine dependent record [ 
blank: [0..377B], ~ not used 
Keysetl, Keyset2, Keyset3, Keyset4, Keysets: updown, 
Red, Blue, Yellow: updown, 
Five, Four, Six, E, Seven, D, U, V, 
Zero, K, Dash, P, Slash, BackSlash, LF, BS: updown, 
Three, Two, W, Q, S, A, Nine, I, 

X, O, L, Comma, Quote, RightBracket, Spare2, Sparel: updown, 
One, ESC, TAB, F, Ctrl, C, J, B, 

Z, LeftShift, Period, SemiColon, Return, Arrow, DEL, FL3: updown, 
R, T, G, Y, H, Eight, N, M, 

Lock, Space, LeftBracket, Equal, RightShift, Spare3, FL4, FR5: updown]; 
Keys: pointer to KeyBits = — magic memory location — ; 

MouseButton: type = {RedYellowBlue, RedBlue, RedYellow, Red, BlueYellow, Blue, Yellow, 
None}; 

MouseBits: type = machine dependent record [ 

blank: [0..377B], — Diablo, Versatec, etc. 

keyset: [0..37B], — 0 => down, i.e. normal state is 37b 

buttons: MouseButton]; 
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Mouse: pointer to MouseBits = — magic memory location — ; 

KeyName: type = { 

. . . , — unused values 

Keyset 1, Keyset2, Keyset3, Keyset4, Keyset5, 

Red, Blue, Yellow, 

Five, Four, Six, E, Seven, D, U, V, 

Zero, K, Dash, P, Slash, BackSlash, LF, BS, 

Three, Two, W, Q, S, A, Nine, I, 

X, 0, L, Comma, Quote, RightBracket, Spare2, Spare 1, 

One, ESC, TAB, F, Ctrl, C, J, B, 

Z, LeftShift, Period, SemiColon, Return, Arrow, DEL, FL3, 
R, T, G, Y, H, Eight, N, M, 

Lock, Space, LeftBracket, Equal, RightShift, Spare3, FL4, FR5}; 

Alto II names for some keys are different. 

FL1: KeyName = DEL; 
FL2: KeyName = LF; 
BW: KeyName = Spare 1; 
FR1: KeyName = Spare3; 
FR2: KeyName = BackSlash; 
FR3: KeyName = Arrow; 
FR4: KeyName = Spare2; 

Keyltem: type = record [ 
Letter: boolean, 
ShiftCode: [0..177B], 
NormalCode: [0..377B]]; 

There is a Keyltem for every key (including mouse and keyset keys). A NormalCode = 0 
causes the key to be ignored; a ShiftCode = 0 puts in a zero for the key when the shift 
key is down; Letter means that the ShiftCode is selected by the shift lock key. Note that 
the ShiftCode is 7 bits and the NormalCode is 8 bits. 

ChangeKey: procedure [key: KeyName, action: Keyltem] returns [oldAction: Keyltem]; 

This procedure changes the meaning of a key and returns the old value. 



Initialization 



BasicMesa does not contain a keyboard package. Clients of BasicMesa who do not wish to supply 
their own keyboard procedures should include keyboard and keystreams in their configurations. 
The following additional definitions from keydefs are needed: 

Keyboard: program; 



Alto/Mesa Keyboard Package 
KeyStreams: program; 

In order to initialize the keyboard process, a client must include these statements: 

FrameDefs.MakeCodeResident[FrameDefs.GlobalFrame[KeyDefs.Keyboard]]; 
start KeyDefs.KeyStreams; 
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This section describes some miscellaneous facilities in Alto/Mesa. 
From MISCDEFS 

Zero: procedure [p: pointer, I: cardinal]; 

for i in[O..I) do (p+i)t <- 0. 
SetBlock: procedure [p: pointer, v: unspecified, I: cardinal]; 

for i in[0..I) do (p+i)t «- v. 

DAYTIME: procedure returns [AltoFileDefs.TIME]; 

Returns the current time in the format maintained by the Alto Operating System and 
recorded in Alto files. This is not the same format as a TimeDefs.PackedTime. 

GetNetworkNumber: procedure returns [cardinal]; 

Returns the number of the network to which the Alto is connected or 0 if there is no 
network or no response from a gateway. 

Fine point: this procedure is used by the Compiler and others to generate unique identifiers for output files. 

CommandLineCFA: procedure returns [pointer to AltoFileDefs.CFA]; 

Returns a pointer to the CFA for the point at which the Mesa executive stopped reading 
the command line (com.cm). This is valid only when a configuration is started from the 
command line using Mesa.image or BasicMesa.image. The caller can use the CFA to 
quickly open a stream on the command line and read any additional commands. The CFA 
should be updated before returning to the Mesa executive. See the sections on Files and 
Streams for more information. 

CallDebugger: procedure [string]; 

This will invoke the Debugger without the overhead of raising an uncaught signal. The 
Debugger may someday display the parameter if it is not nil. 

From inlinedefs (these are all machine code procedures) 

COPY: procedure [from: pointer, nwords: cardinal, to: pointer]; 

for i in[0. .nwords) do (to+i)t «- (from+i)t, 
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DIVMOD: procedure [num, den: cardinal] returns [quotient, remainder: cardinal]; 

Returns both the quotient and remainder of the unsigned division of num by den. 

LDIVMOD: procedure [numlow: word, numhigh: cardinal, den: cardinal] returns [quotient, 
remainder: cardinal]; 

Like DIVMOD except that the numerator is the double length unsigned number 
numhigh*2 16 + numlow. Results are undefined if the quotient is greater than 2 16 -1. 

LongCARDINAL: TYPE = MACHINE DEPENDENT RECORD [ 

lowbits, highbits: cardinal]; 

A LongGARDINAL is an unsigned double precision number which is a valid argument to 
several Mesa byte codes. A long integer which is known to be positive may be LOOPHOLEd 
to a LongCARDINAL; a LongCARDINAL which is less than 2 31 may be LOOPHOLEd to a long 
integer. 

LongMult: procedure [cardinal, cardinal] returns [product: LongCARDINAL]; 

Returns the double precision result of the unsigned multiplication the two single 
precision arguments. 

LongDiv: procedure [num: LongCARDINAL, den: cardinal] returns [cardinal]; 

Returns the result of the unsigned division of num by den. Result is undefined if the 
quotient is greater than 2 16 -1. 

LongDivMod: procedure [num: LongCARDINAL, den: cardinal] returns [quotient, remainder: 
cardinal]; 

Like LongDiv except both quotient and remainder are returned. 

BITAND, BITOR, BJTXOR: PROCEDURE [WORD, WORD] RETURNS [WORD]; 

These functions compute the bitwise and, or, or xor of their arguments. 

BITNOT: PROCEDURE [WORD] RETURNS [WORD]; 

Returns the ones complement of the input. 

BITSHIFT: procedure [value: word, count: word] RETURNS [WORD]; 

Returns value shifted by ABS[count] bits. Shift is left if count > 0 and right if count < 
0. 

From doubledefs. (DAdd, DSub, and DCompare are machine code procedures and are available to 
any Mesa program. The others are available only to clients which include double in their 
configuration.) 
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DAdd: PROCEDURE [a,b: LongCARDINAL] RETURNS [LongCARDINAL]; 

Returns the double precision unsigned sum of a and b.. 
DSub: procedure [a,b: LongCARDINAL] returns [LongCARDINAL]; 

Returns the double precision unsigned difference of a and b. 
Comparison: type = {less, equal, greater}; 

DCompare: procedure [a,b: LongCARDINAL] returns [Comparison]; 

Returns less if a<b, equal if a=b, greater if a>b. Comparison is actually done by subtracting and 
comparing the result to 0. 

DMultiply: procedure [a,b: LongCARDINAL] returns [product: LongCARDINAL]; 

Returns the product of the unsigned multiplication of a by b. 

DDivide: procedure [num, den: LongCARDINAL] returns [quotient, remainder: 
LongCARDINAL]; 

Returns the quotient and remainder of the unsigned division of num by den. 

DNeg: procedure [a: LongCARDINAL] returns [LongCARDINAL]; 

While somewhat a contradiction in terms, this procedure negates a LongCARDINAL by 
performing DSub[[0,0], a]. 

Dine: PROCEDURE [a: LongCARDINAL] returns [LongCARDINAL]; 

DAdd[[1,0], a]. 

AppendDouble: procedure [s: string, a: LongCARDINAL]; 

The value of a is converted to text in decimal and appended to s. 

Floating Point 

While the Mesa system does not provide any support for floating point operations, the Compiler 
does recognize type real and generates calls to client supplied procedures via the system data 
vector (SD). The definitions of SD and all indices into SD are in sddefs. In the following 
description the notation 

SDpndex]: procedure ... 

means that the client should declare a procedure P of the correct type and assign its descriptor to 
the appropriate element of SD (SD[index] *- P). The Compiler makes no assumptions about the 
representation of reals except that they occupy two words. 
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SD[sFADD]: PROCEDURE [a, b: REAL] RETURNS [REAL]; 

Called to perform addition. 
SD[sFSUB]: procedure [a, b: real] returns [real]; 

Called to perform subtraction. 
SD[sFMUL]: procedure [a, b: REAL] returns [real]; 

Called to perform multiplication. 
SD[sFDIV]: procedure [a, b: real] returns [real]; 

Called to perform division (a/b). 
SD[sFCOMP]: procedure [a, b: real] returns [integer]; 

Called to compare reals. Return -1 if a<b, 0 if a=b, 1 if a>b. 

SD[sFLOAT]: PROCEDURE [LONG INTEGER] RETURNS [REAL]; 

Called to convert fixed point to floating point 

SD[SFIX]: PROCEDURE [REAL] RETURNS [LONG INTEGER]; 

The Compiler does not generate calls to this procedure. It is included for completeness. 
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This section documents the operations required to manipulate modules at a more detailed level 
than provided by the language. It is intended for experienced programmers who have a genuine 
need to manipulate low level system structures. See framedefs for further details. 

Global Frames 

A GlobalFrame is the implementation of the program language construct. All manipulation of 
GlobalFrames is done using GlobalFrameHandles. 

GlobalFrameHandle: type = pointer to GlobalFrame; 

GlobalFrame: type = record [. . .]; 

The procedures which manipulate global frames are: 

GlobalFrame: procedure [link: unspecified] returns [GlobalFrameHandle]; 

Returns the GlobalFrameHandle corresponding to link, which is interpreted as a control 
link; it should be either a procedure, pointer to frame or program. If link is not a valid 
control link, then either the signal InvalidGlobalFrame or UnboundProcedure will be raised 
(see the section on Traps for a description of UnboundProcedure). 

ValidateGlobalFrame: procedure [GlobalFrameHandle]; 

Checks to see that the parameter is a valid global frame; InvalidGlobalFrame is raised if 
not. Used to check the validity of GlobalFrameHandle parameters by system procedures 
such as GlobalFrame. 

InvalidGlobalFrame: signal [frame: GlobalFrameHandle]; 

Indicates that frame does not point to a valid global frame. 

EnumerateGlobalFrames: procedure [ 

proc: procedure [GlobalFrameHandle] returns [boolean]] 
returns [GlobalFrameHandle]; 

Calls proc once for each global frame currently defined. If proc returns true, 
EnumerateGlobalFrames returns the GlobalFrameHandle of the last frame processed. If all 
global frames have been processed, NullGlobalFrame is returned. 

Warning: If new modules are created while EnumerateGlobalFrames is in control, it is not 
guaranteed that they will be included in the sequence of GlobalFrameHandles passed to 
proc. 
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Module Creation / Deletion 

The following procedures allow the programmer explicit control over the creation and deletion of 
modules. New and Copy provide a more detailed interface for loading modules than provided by 
the new language construct (which is implemented by these operations). UnNew and 
UnNewConfig allow the deletion of previously loaded modules and configurations. New, Copy 
and UnNew are defined as machine code procedures in framedefs and cannot not be imported. 

New: procedure [name: string] returns [frame: GlobalFrameHandle]; 

Loads the bcd contained in the file name. Returns the GlobalFrameHandle for the control 
module of the configuration (or the module itself if the bcd is a single module). Returns 
NullGlobalFrame if the configuration has no control module. 

Fine point: until the language supports NEW on an arbitrary configuration, this is the only way of loading a 
configuration containing more than one module. 

Copy: procedure [old: GlobalFrameHandle] returns [new: GlobalFrameHandle]; 

Makes a new global frame that is a copy of old. The new frame shares code with the old 
frame and is bound the same way. 

Warning: if the old global frame is not completely bound and its external links are stored 
in the global frame, the copy may not be completely bound, even if the unbound 
externals of the old frame are later resolved. 

UnNew: procedure [frame: GlobalFrameHandle]; 

Deletes the global frame pointed to by frame. Returns the global frame to the frame 
heap (if the frame was allocated from that heap). Deletes the code segment of the frame 
if no other global frames share it 

Warning: there is no check for references that are bound to the module being deleted. 

UnNewConfig: procedure [frame: GlobalFrameHandle]; 

Deletes all global frames that are a part of the configuration containing frame, as well as 
all copies of those frames. Frees the storage for the global frames (to the segmentation 
machinery if it was obtained from there, or the the frame heap). 

Fine point: UnNewConfig is defined in LOADERDEFS. 

NoGlobalFrameSlots: signal; 

Indicates that there is no room in the Global Frame Table when either New or Copy have 
been called. 

# 

Fine point: global frames for single modules (and copies) are allocated from the frame heap. Other configurations 
allocate their global frames as a single (data) segment, and are subject to some wasted space due to breakage. 

Other signals may be raised when Newing modules; these signals indicate that the bcd being 
loaded is invalid, versions of interfaces don't match, or code files cannot be found. In addition, 
when a module is started, the signal StartFault may be raised (see the section on Traps for more 
information). 
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Code Manipulation 

The following procedures enable the user to control code swapping. 

MakeCodeResident: procedure [f: GlobalFrameHandle]; 

Swaps in the code for f as low as possible in memory by pushing unlocked read-only 
segments out of the way. It will first swap out the code if it is swapped in. 

LockCode: procedure [link: unspecified]; 

Swaps in and locks the code segment associated with link (which may be either a 
procedure, pointer to frame or program). The procedure GlobalFrame is used to find the 
global frame of link (and may raise the signals InvalidGlobalFrame and 
UnboundProcedure). 

Warning: calling LockCode on a global frame that has not been started will disable start 
traps on that module. 

UnlockCode: procedure [link: unspecified]; 

Unlocks the code segment associated with link (which may be either a procedure, pointer 
to frame or program). The procedure GlobalFrame is used to find the global frame of 
link (and may raise the signals InvalidGlobalFrame and UnboundProcedure). 

SwapOutCode: procedure [f: GlobalFrameHandle]; 

Swaps out the code for f. 

Fine point: when a frame has its code swapped out, all the global frames that have the same code segment 
will be updated to reflect the fact that the code is swapped out. These other frames either have their code 
segments packed with that frame or they are copies of that frame. Code may be swapped out by clients 
calling SwapOutCode or by the system. 

SwaplnCode: procedure [f: GlobalFrameHandle]; 

Swaps in and locks the code for f. 

Warning: calling SwaplnCode on a global frame that has not been started will disable 
start traps on that module. 
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This section has been taken from the Pilot Functional Specification and slightly modified to 
reflect the Alto/Mesa implementation. 

Warning: The Alto/Mesa operating system software has not been revised and redesigned to 
fully exploit the capabilities of the new process mechanism. In particular, arbitrary preemptive 
processes are not supported, and the restrictions of Mesa 3.0 on processes running at interrupt 
level still apply. 

Most aspects of processes and monitors are made available via constructs built into the Mesa 
language and described in Chapter 10 of the Mesa Language Manual (version 4.0, to be published). 
Some facilities whose frequency of use does not justify such treatment are cast as procedures, and 
form part of the Mesa system. The types and procedures described below are defined in 

PROCESSDEFS. 

PSB: PRIVATE TYPE = MACHINE DEPENDENT RECORD [...]; 

ProcessHandle: private type = pointer to PSB; 

A PSB defines the data structure underlying the Mesa process implementation. In general 
no client programs should be concerned with these types (except possibly for debugging). 

Any of the operations which take a process as an argument (i. e., join, Abort, and Detach) may 
generate the following signal. 

InvalidProcess: signal [process: ProcessHandle]; 

This signal indicates that the process argument does not correspond to any process known 
to the Mesa system. The cheek on the validity of the argument is not infallible. In particular, Mesa is 
unable to distinguish between a process which has been deleted and a new, recently created one which 
coincidentally has the same value. 

A call to fork may generate the following signal. 

TooManyProcesses: error; 

The Mesa system contains a fixed number of PSBs. This signal will result when there are 
no PSBs available to create a new process. 



Initialization 

Every instance of a monitor and every condition variable must be initialized before it can be 
used. There are two cases: 

If the lock and the condition variables reside in the global frame (or possibly the local 
frame, in the case of the condition variables) Mesa will automatically initialize them 
along with the other global/local variables when the module is STARTed or the procedure 
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is entered. 

If the lock and/or condition variables reside in client-allocated recgrds, initialization is 
the responsibility of the client. 

Using uninitialized monitor locks or condition variables or reinitializing monitor locks or condition variables 
after they have have begun to be used will lead to totally unpredictable behavior. 

The following operations are provided for initializing monitor locks and condition variables in 
client-created data structures. 

InitializeMonitor: procedure [monitor: pointer to monitorlock]; 

InitializeMonitor leaves the monitor unlocked and sets the queue of waiting processes to 
empty. It may be called before or after the monitor data is initialized, but must be called 
before any entry procedure is invoked. Once use of the monitor has begun, 
InitializeMonitor must never be called again. 

Ticks: type = cardinal? 

InitializeCondition: procedure [condition: pointer to condition, ticks: Ticks]; 

InitializeCondition sets the queue of waiting processes to empty and sets the timeout 
interval of the condition variable to ticks (measured in units of "ticks" of an internal 
clock). It may be called before or after the other monitor data is initialized, but must be 
called before any wait or notify operations are performed on the condition variable. Once 
use of the condition variable has begun, InitializeCondition must never be called again. 



Clients may convert clock ticks to or from milliseconds using the following operations. 
MsecToTicks: procedure [cardinal] returns [Ticks]; 
TicksToMsec: procedure [Ticks] returns [cardinal]; 



Timeouts 

Condition variables which are initialized automatically are assigned a default timeout of a few 
seconds. The timeout of any condition variable may be changed by the following operation. 

SetTimeout: procedure [condition: pointer to condition, ticks: Ticks]; 

DisableTimeout: procedure [pointer to condition]; 

SetTimeout adjusts the timeout interval for all subsequent wait operations applied to that 
condition variable. DisableTimeout disables timeouts for all subsequent wait operations 
applied to that condition variable. However, neither operation has any effect on 
processes which are already WAiTing. 

SetTimeout and DisableTimeout are the only available operations to adjust a condition 
variable once it has been used. In particular, InitializeCondition must not be used for this 
purpose, especially for condition variables which are automatically initialized. 
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Detaching Processes 

A process which will never be joined is detached using the following operation. 

Detach: procedure [process]; 

This operation sets the state of the process so that when it returns from its root 
procedure, it will be deleted immediately and its results, if any, will be discarded. If the 
process is invalid (e. g., if the process has already been deleted), the signal InvalidProcess 
may be generated. 

The argument to Detach is actually of type UNSPECIFIED, and is validated as a PROCESS at run-time. This is 
necessary since there is no generic type which includes all PROCESS types, regardless of result types. 



Priorities of Processes 

When a process is created with fork, it inherits the priority of the FORKing process. If this proves 
unsatisfactory, the FORKed process may change its own priority with the following operation. 

SetPriority: procedure [Priority]; 

Priority: type = [0..7]; 

A process may determine its own priority by calling: 
GetPriority: procedure returns [Priority]; 

There is no way for a process to alter the priority of another process. 

CAUTION: Use of multiple priorities in the Alto/Mesa implementation is severely restricted. 
Any process running at other than the default priority (currently, 1) is forbidden to use many of 
the standard runtime support features of the Mesa environment. In practice, this means that 
non-standard priorities should be used only for interrupt handling, while all "normal" processing 
takes place concurrently af the default priority level. In addition, all interrupt level code must be 
locked in memory and should perform only a minimal amount of processing. 



Aborting a process 

A process can be aborted by calling the following operation. 

Abort: procedure [process]; 

The effect of this operation is to generate the signal Aborted the next time the process 
executes a wait statement on any condition variable. If the process is already WAiTing, an 
implicit notify is issued at the time this procedure is called. 

The argument to Abort is actually of type UNSPECIFIED, and is validated as a PROCESS at run-time. This is 
necessary since there is no generic type which includes all PROCESS types, regardless of result types. 
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Aborted: error; 

The catch phrase for this signal may be attached to the wait statement, or it may be 
enabled in some scope according to the scope rules of Mesa. The catch phrase is executed 
with the corresponding monitor locked. 

The intended use of Abort is to provide a means whereby one process may hint to another that the latter 
should go away, after first cleaning up. An Abort signal may occur on any condition variable, and thus every 
monitor should be protected by some catch phrase for it. 



Control of scheduling 

The Mesa process mechanism does not attempt to allocate processor time fairly among processes 
of equal priority. Because of this, it may be desirable for a process which does not does not 
execute wait statements very frequently in the normal course of its computation to occasionally 
yield control of the processor by calling the following operation. 

Yield: procedure; 

This is a hint to the scheduler to run other processes of the same priority. However, there 
is no guarantee that any other process mil execute before the calling process resumes 
execution, even if there are processes able to execute. 

In no case must the logical correctness of client programs depend on the presence or absence of calls to Yield; 
priorities and yielding are not intended as a process-synchronization mechanism. They are only hints to 
assist clients in meeting performance requirements. 



Interrupt Level Processes 

This section refers only to the Alto/Mesa implementation. It should be of interest only to 
programmers of interrupt level code. 

The Mesa monitor mechanism includes an extension to cover the case of communication between 
software processes and Input/Output controllers (hardware and/or firmware). This is done using 
the artifact of naked condition variables] that is, condition variables which are not effectively 
protected by a monitor lock. The need for this arises from the fact that communication with 
I/O controllers, while similar to normal interprocess communication, suffers from the problem 
that the controllers are intrinsically unable to enter monitors. This means that two important 
atomicity properties provided by monitor locks are lost: 

Atomicity of wakeups: Monitor locks eliminate the need for a traditional "wakeup 
waiting" (or "interrupt pending") flag. Lack of the monitor lock requires the provision of 
such a flag if lost interrupts are not to result 

Atomicity of data manipulations: The monitor lock avoids the problems of critical races 
on shared data; traditionally, I/O architectures take an ad hoc approach to this problem, 
rather than providing any general mechanism. 

The approach taken is to solve the first problem in a general way, and leave the second problem 
for case-by-case resolution by the designers of specific controller/software interfaces. (This 
closely mirrors the approach normally , taken in more traditional I/O-interrupt architectures.) 
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A software process that deals with an I/O controller does so from within what appears to be a 
normal monitor. The monitor data includes the status and control blocks of the device and a 
condition variable which the device notifies to raise an "interrupt". Since the controller can 
access the shared data at any time, however, special care must be taken by the software to avoid 
conflicts. Similarly, if the controller tried to notify the software between the time it decided to 
wait on the condition variable, and the time that it actually performed the wait operation, the 
notify would be lost. To prevent this, the controller does a special form of notify (a naked 
notify), which sets a wakeup-waiting flag in the condition variable. This difference is invisible 
to the software, which does a normal wait operation on the condition variable. 

The traditional operations Enablelnterrupts and Disablelnterrupts are provided for those rare 
circumstances in which seizing the entire machine is the only form of mutual exclusion which 
proves sufficient. Doing a WAIT while interrupts are disabled is not recommended. 

InterruptLevel: type = [0..15]; 

InterruptLevels correspond to the interrupt channels described in the Alto Hardware 
Manual (except that the numbering is different). Interrupt level 0 corresponds to Alto 
interrupt channel 15, the memory parity interrupt channel. Several levels are used by the 
Mesa system. Programmers of interrupt level code should see the definitions in 

PROCESSDEFS. 

ConditionVector: type = array InterruptLevel of pointer to condition; 

CV: pointer to ConditionVector = — magic constant — ; 

CV points to an array of pointers to the naked condition variables described above. To 
associate a condition with an interrupt level, assign a pointer to the condition to the 
corresponding element of CV (CVpevei] «- @cVar). To disable the naked notifys, assign 
nil. 

Disablelnterrupts, Enablelnterrupts: procedure; 

These are machine code procedures which disable and enable the handling of interrupts at 
the lowest level. They should be used only in matching pairs and only when no other 
exclusion mechanism will suffice. A counter is maintained of the number of unmatched 
Disablelnterrupts so that nested pairs will work correctly. 
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The Mesa virtual memory (VM) is organized as a vector of pages of size PageSize words; the last 
page is MaxVMPage. VM is occupied by segments: a segment is an integral number of pages in 
length and the words in a segment are all linearly addressable; segments have no empty holes in 
them. There are two variants of segments: data and file. Data segments are associated directly 
with memory and are not swappable or movable; file segments correspond to contiguous groups 
of pages in a file and may be swapped in and out of virtual memory. 

Client programs access segments using SegmentHandles, which are pointers to SegmentObjects. 
A SegmentObject contains the information necessary to describe the segment. Although there 
are some routines that deal with SegmentHandles, segments are not particularly interesting 
unless they are discriminated as to data or file variant. 

Client programs access file segments using FileSegmentHandles, which are pointers to file 
SegmentObjects. A file segment contains sufficient information to compute its address if the 
segment is swapped in. Internally, the segmentation package maintains a set of objects called 
FileObjects: a file object, among other things, contains the file's disk address and serial number, 
as well as its access rights. The association between a segment and a file is made when the 
segment is created. The Mesa file package is documented separately. 

Segments may also be pages in VM rather than attached to a file. Such data segments are not 
swappable or movable in any way (relative to the Mesa virtual memory). Thus, absolute pointers 
into a data segment are valid for the lifetime of the segment. DataSegmentHandles and data 
SegmentObjects are used to record information about these segments. See segmentdefs for 
further details. 



As mentioned above, segment objects come in two varieties: data segments and file segments The 
following structure contains the necessary information: 

SegmentHandle: type = pointer to SegmentObject; 

SegmentType: type = {data, file}; 

SegmentObject: type = record [ 



Segments 



. . . j 



select type: SegmentType from 
data => [ 



VMpage: [0. .MaxVMPage], 
pages: [ 1 ..MaxVMPage+ 1 ] 



— VM page number 

— number of pages 




swappedin: boolean, 
read, write: boolean, 



true /// segment is in 
access options 
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class: FileSegmentCfass, 
lock: [CMaxLocks], 
file: FileHandle, 
base: PageNumber, 
pages: [ 1 ..MaxVMPage+ 1 ], 
VMpage: [O..MaxVMPage], 

■ . 
endcase]; 



— {code, other} 

— locking reference count 

— see the file package 

first page of the file to include 

— number of pages, beginning with base 

— if swapped in, VM page number 



The procedures which manipulate undiscriminated segments are: 

VMtoSegment: procedure [a: pointer] returns [SegmentHandle]; 

The handle for the segment* containing the specified address (as currently laid out in 
memory) is returned; nil is returned if no segment contains it. This does not imply that 
the page containing the address is free, however; it may be reserved for some operation 
currently in progress. 

SegmentAddress: procedure [seg: SegmentHandle] returns [pointer]; 

The address of the beginning of the segment is returned; nil is returned if the segment is a 
file segment and not currently swapped in. To guarantee the validity of the address the 
segment should be locked when this procedure is called (see below), since the system may 
swap out file segments which are not locked. Beware of dangling references! 



Data Segments 

Data segments are associated only with virtual memory (there is no swapping file), and are never 
moved or swapped out. 

DataSegmentHandle: type = pointer to DataSegmentObject; 
DataSegmentObject: type = data SegmentObject; 

The procedures which manipulate data segments are: 

NewDataSegment: procedure [base: PageNumber, pages: PageCount] 
returns [DataSegmentHandle]; 

Creates a new data segment and returns a handle for it. If base is DefaultBase then the 
segment is allowed to begin on any free page in memory. If base is an actual page 
number (in [C.MaxVMPage]), an attempt is made to place the segment at that location. 
Note that pages should not be defaulted. 

DataSegmentAddress: procedure [seg: DataSegmentHandle] returns [pointer]; 

Returns a pointer to the base of the segment in virtual memory. In the current 
implementation, segments always begin on a page boundary; this may not be true in the 
(distant) future. 
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VMtoDataSegment: procedure [a: pointer] returns [DataSegmentHandle]; 

The handle for the segment containing the specified address (as currently laid out in 
memory) is returned, nil is returned if no data segment contains it. This does not imply 
that the page containing the address is free, however; it may be assigned to a file segment, 
or reserved for some operation currently in progress. 

DeleteDataSegment: procedure [seg: DataSegmentHandle]; 

The specified data segment is deleted and its segment object freed. When a segment is 
successfully deleted, any VM which it occupied becomes free. 

EnumerateDataSegments: procedure [ 

proc: procedure [DataSegmentHandle] returns [boolean]] 
returns [DataSegmentHandle]; 

Calls proc once for each data segment currently defined. If proc returns true, 
EnumerateDataSegments returns the handle of the last segment processed. If the end of 
the set of data segments is reached, nil is returned. 

If data segments are created while EnumerateDataSegments is in control, it is not guaranteed that 
they will be included in the sequence of DataSegmentHandles passed to proc. 



File Segments 

Unlike data segments, file segments are associated with a contiguous group of pages in a file and 
are therefore swappable. Pointers into a file segment are valid only while it is swapped in (and 
locked so that it will not be swapped out). A file segment which is swapped out occupies no 
space in virtual memory, other than the segment object which describes it. 

FileSegmentHandle: type = pointer to FileSegmentObject; 

FileSegmentObject: type = file SegmentObject; 

To create new file segments, use 

NewFileSegment: procedure [ 

file: FileHandle, base: PageNumber, pages: PageCount, access: AccessOptions] 
returns [FileSegmentHandle]; 

Creates a new segment and returns a handle for it. The segment is associated with the 
corresponding file pages, but the file is not opened and the segment is not swapped in. If 
base is DefaultBase, the segment will begin with the first data page of the file, and if 
pages is DefaultPages, it will include the last page of the file. Although it is generally 
not done, a segment can begin with the leader page (page zero) of a file. Finally, if 
access is DefaultAccess, read access is assumed. 

If the access specifies that changing the data is permitted, then whenever it is necessary to swap 
this segment out and remove its pages from memory, pages will be written to the file (the Alto 
has no hardware to detect if the pages have actually been changed). Note that it is possible to 
change the segment's access (by setting the write bit, for example), provided the file to which it is 
attached has the appropriate access rights. 
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FileSegmentAddress: procedure [seg: FileSegmentHandle] returns [pointer]; 

The address of the beginning of the segment is returned. The signal SwapError is raised 
if the segment is not currently swapped in. To guarantee the validity of the address, the 
segment should be locked when this procedure is called (see below), since the system may 
swap out file segments which are not locked. Beware of dangling references! 

VMtoFileSegment: procedure [a: pointer] returns [FileSegmentHandle]; 

The handle of the file segment containing the specified address (as currently laid out in 
memory) is returned; nil is returned if no file segment contains it. This does not imply 
that the page containing the address is free, however; it may be assigned to a data 
segment, or reserved for a segment currently being swapped in. 

DeleteFileSegment: procedure [seg: FileSegmentHandle]; 

The specified file segment is deleted and its segment object is released. If the segment is 
swapped in, it is first swapped out (it should not be locked). If there are no other 
segments associated with this segment's file (the file's segcount is zero), then ReleaseFile 
is called to release the FileObject. When a segment is successfully deleted, any VM which 
it may have occupied becomes free, 

EnumerateFileSegments: procedure [ 

proc: procedure [FileSegmentHandle] returns [boolean]] 
returns [FileSegmentHandle]; 

Calls proc once for each data segment currently defined. If proc returns true, 
EnumerateFileSegments returns the handle of the last segment processed. If the end of 
the set of data segments is reached, nil is returned. 

If file segments are created while EnumerateFileSegments is in control, it is not guaranteed that 
they will be included in the sequence of FileSegmentHandles passed to proc. 



Window Segments 

A window segment is similar to a file segment, except that the base and pages fields of the 
segment may be altered (using the procedures described below) after it is created, in order to slide 
the window around in a file or to vary the window's size. In reality, all file segments are in fact 
window segments, and may be moved with the following procedure: 

MoveFileSegment: procedure [seg: FileSegmentHandle, base: PageNumber, pages: PageCount]; 

If the segment is swapped in, it is first swapped out (it should not be locked). The 
segment is then moved to the new location in the segment's file, but it is not swapped in. 
The base and pages are defaulted as in NewFileSegment. 

Fine point: in the current implementation, the disk address of the original segment is retained as a hint 
about the new location, thus improving performance considerably when a one page segment is slid forward or 
backward in a file. 

If the original and final position of the segment overlap, there is no guarantee that the 
overlapping pages are actually written, nor is it guaranteed that a minimum number of pages are 
transferred. The segment package reserves the option to implement (or not to implement) such 
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optimizations in the future. 



Swapping Segments 

A segment can be swapped into and out of VM. The procedures and signals which implement 
this are described in this section: 

Swapln: procedure [seg: FileSegmentHandle]; 

Swaps in the specified segment (if it is swapped out), opening the associated file if 
necessary; locks it so it won't be moved or swapped out. A SwapError will result if the 
segment already has MaxLocks locks on it, or if the segment's file has MaxRefs segments 
currently attached to it and swapped in. 

To unlock a segment (allow it to be swapped), use the procedure 

Unlock: procedure [seg: FileSegmentHandle]; 

Unlocks the specif ed segment so that it can be swapped out Note that locking behaves 
like reference counting, so that locks (performed by Swapln) must be properly paired 
with Unlocks. 

A segment is swapped out using 

SwapOut: procedure [seg: FileSegmentHandle]; 

Swaps out the specified segment, writing the pages back to the file if the segment's access 
makes this necessary, and free the segment's VM pages. If the segment is locked, a 
SwapError will be generated. 

A program may explicitly request that the file pages corresponding to a segment be updated by 
calling: 

SwapUp: procedure [seg: FileSegmentHandle]; 

Write the pages of the segment back to the file if the access requires it. This operation 
does not unlock the segment or free the segment's VM pages. 

Note that neither Swapln, SwapOut, or SwapUp are capable of extending a file (physically adding 
pages or bytes to it) based on the size of a segment. Segments may be attached only to pages of a 
file that are already allocated on the disk (and chained together). Extending (or contracting) a 
file must be done using other mechanisms (for example, see SetEndOfFile in the file package). 



Signals 

The following signals may be generated by the segment package: 
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InvalidSegmentSize: signal [pages: PageCount]; 

In NewDataSegment or NewFileSegment a zero length segment has been requested, or the 
length exceeds the size of virtual memory. 

InsufficientVM: signal [needed: PageCount]; 

In NewDataSegment or Swapln there is not enough contiguous memory to accomodate a 
segment; needed is the number of pages that are actually required. If resumed, the 
allocation will be retryed; this gives the catcher of this signal a chance to free up some 
VM. Users can free VM pages by deleting data segments and by allowing locked segments 
to become swappable (see also the section below on swapping strategies). 

VMnotFree: signal [base: PageNumber, pages: PageCount]; 

In NewDataSegment the base was not DefaultBase and the specified memory pages 
were not free. 

SwapError: signal [seg: FileSegmentHandle]; 

An invalid swapping operation was attempted with seg. 

SegmentFault: signal [seg: FileSegmentHandle, pages: PageCount]; 

End of file was encountered while attempting to swap the segment in or out; pages is the 
actual number of pages in the segment If pages is greater than zero then the signal may 
be resumed; the segment will be truncated accordingly (of course, this will not alter the 
file length). 



Low Level Memory Allocation 

Operations are provided for users that have a need to control memory allocation at a lower level 
than provided above. Allocation is controlled by the information in an Alloclnfo (which is 
passed along with each operation). 

Alloclnfo: type = record [ 

effort: {hard, easy}, 

direction: {topdown, bottomup}, 

. . . ]; 

If the effort field is hard, unlocked read-only file segments will be pushed out of the way. The 
direction field specifies the direction of the search for a hole. In the above procedures, data 
segments are allocated topdown, and file segments are allocated bottomup. See allocdefs for 
further information. 



The operations which form the low-level memory allocation are: 
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MakeDataSegment: procedure [base: PageNumber, pages: PageCount, info: Alloclnfo] 
returns [DataSegmentHandle]; 

Acts like NewDataSegment, except info is passed as an additional parameter; the same 
restrictions apply and the same signals may be generated. 

MakeSwappedln: procedure [seg: FileSegmentHandle, base: PageNumber, info: Alloclnfo]; 

Acts like Swapln, except info and base are passed as additional parameters; the same 
restrictions apply and the same signals may be generated. If base is DefaultBase then the 
segment is allowed to begin on any free page in memory. If base is an actual page 
number (in [O..MaxVMPage]), an attempt is made to place the segment at that location 
(VMnotFree will be raised if the specified pages are not available). 



Swapping Strategies 

A mechanism is provided for informing the segmentation package of emergency measures which 
can be taken when the signal InsufficientVM is (about to be) generated. These measures take the 
form of SwappingProcedures which, when called by the swapping manager, attempt to make 
more room in virtual memory and return a boolean indicating their success or failure to do so. 
The swapping manager invokes each procedure in turn, retrying the allocation after each 
procedure which has indicated success, until sufficient memory is obtained. If all such 
procedures indicate failure, the signal InsufficientVM is raised (the swapping manager is not 
crying wolf!). 

The swapping strategies are maintained as a linked list of SwapStrategy nodes whose procedures 
are invoked from head to tail. 

SwappingProcedure: type = procedure [ 

needed: PageCount, info: Alloclnfo, seg: SegmentHandle] 
returns [boolean]; 

The following parameters are supplied to swapping procedures to allow them the make intelligent 
decisions about making room: needed is the number of pages requested, info the Alloclnfo 
supplied to the allocator, and seg the file segment that will use the allocated memory (nil if the 
segment is not known). 

SwapStrategy: type = record [ 
link: pointer to SwapStrategy, 
proc: SwappingProcedure]; 

The swapping manager initializes the list with a single node which invokes code swapping as a 
last resort. 

StrategyList: pointer to SwapStrategy «- ©LastResort; 
LastResort: SwapStrategy = SwapStrategy [nil, TryCodeSwapping]. 

Swapping procedures are added to and removed from the list by the procedures: 
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AddSwapStrategy: procedure [strategy: pointer to SwapStrategy]; 

The specified strategy node strategy is added to the head of the list of swapping 
procedures. If strategy is already on the list, its position and content are not disturbed. 

RemoveSwapStrategy: procedure [strategy: pointer to SwapStrategy]; 

The specified strategy node s is removed from the list of swapping procedures. 

Currently, TryCodeSwapping uses an (approximately) LRU (least-recently-used) algorithm to 
choose a code segment to swap out. Only code segments which are not locked are considered. 
Unlocked read-only file segments are also swapped out by TryCodeSwapping. 

Since it is unattractive to require that swapping strategies (other than TryCodeSwapping) be 
locked, swapping procedures should observe the following conventions. If such a procedure 
obtains a state in which it has nothing to swap, it should either remove the node containing it 
from the strategy list or change the procedure in the node to be 

CantSwap: SwappingProcedure; 

Because CantSwap is part of the swapping manager (and therefore locked), this will avoid 
swapping in a strategy procedure which knows it has nothing to do. 



Miscellaneous Procedures 

The following procedures implement conversion between memory addresses and virtual memory 
page numbers. 

PageFromAddress: procedure [a: pointer] returns [PageNumber]; 

AddressFromPage: procedure [p: PageNumber] returns [pointer]; 

PagePointer: procedure [a: pointer] returns [pointer]; 

PagePointer returns the address of the beginning of the page which contains its argument. 

The following procedures implement conversion between FileSegments and DataSegments. Note 
that both segments must exist at the time of the call, and neither is destroyed. They must be of 
the same length (a SwapError will result otherwise). 

CopyDataToFileSegment: procedure [dataseg: DataSegmentHandle, fileseg: FileSegmentHandle]; 

initializes a file segment to be the contents of a data segment. 
CopyFileToDataSegment: procedure [fileseg: FileSegmentHandle, dataseg: DataSegmentHandle]; 

initializes a data segment to be the contents of a file segment. 
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Two collections of Mesa procedures are available for acquiring and managing storage areas. The 
segmentation machinery, which is described in detail elsewhere, provides contiguous groups of 
pages (256 word blocks) in the virtual memory. A simplified interface with that machinery is 
described below. There is also a Mesa free storage package for managing arbitrarily sized nodes 
within free storage zones. Since all state information is recorded within the zones themselves, 
the system-provided instantiation of the latter package can manage an arbitrary number of zones. 
There is one system-defined zone, called the free storage heap, available for general use; special 
procedures exist for creating and destroying nodes within it. The salient characteristics of these 
packages are summarized below. 

The segmentation machinery is most suitable for obtaining large blocks of storage. All 
bookkeeping information associated with such blocks is recorded in auxiliary tables that are 
managed by the segmentation system, not in the blocks themselves. Allocating or releasing a 
segment involves searching and updating a number of those tables. On the other hand, any freed 
page becomes available for general use by the system (loading, buffering, etc.) and any two 
adjacent free pages can be coalesced to become part of a new segment. 

The free storage package is a transliteration of a BCPL program by Ed McCreight that was itself 
based upon a suggestion by Don Knuth (Volume 1, p. 453, #19). Within a zone, free nodes are 
kept as a linked list. One hidden word containing bookkeeping information is stored with each 
allocated node, and additional bookkeeping information is kept in the header of each zone. 
Allocation and release of nodes are usually very fast. Adjacent free nodes are always able to be 
coalesced. It is also possible to add new areas of storage to enlarge a zone. These new areas are 
linked together so that they may be deleted if all the nodes in an area are free; in addition, an 
entire zone may be deleted. 

The free storage package performs best when the sizes of nodes are small compared to the sizes 
of the block(s) making up the zone. In particular, the system's heap is intended to be used for 
small, transient data structures, such as the nodes of a temporary list structure or the bodies of 
(short) strings when the maximum length must be computed dynamically or the structure must 
outlive the frame that creates it. Use of the heap for large (i.e., multipage) nodes decreases 
flexibility in storage management, since the additional pages may become a permanent part of the 
zone. 

Note: Each zone is protected by a monitor. This allows several processes to share the same zone 
safely. 

The allocators in both packages return absolute pointers; allocated nodes are not relocatable and 
there is no garbage collection or automatic deallocation of any sort. Also, the values returned by 
the allocators are free pointers (type pointer to unspecified) which must be cast appropriately 
(usually by assignment) before they can be used. 
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Segmentation Interface 

The following definitions are contained in systemdefs. 

AllocateSegment: procedure [nwords: cardinal] returns [base: pointer]; 

Allocates a segment of virtual memory containing at least nwords words and returns the 
address of the first word in that segment. AllocateSegment provides a simple interface to 
NewDataSegment for allocating VM segments only; see the description of that procedure 
for further explanation. 

AllocateResidentSegment: procedure [nwords: cardinal] returns [base: pointer]; 

Behaves like AllocateSegment, except that unlocked read-only file segments are pushed 
out of the way when the segment is allocated. 

SegmentSize: procedure [base: pointer] returns [nwords: cardinal]; 

Returns the number of words actually obtained in the segment 

These procedures allow complete utilization of segments obtained without knowledge of page 
structure and guaranteed only to have some minimum size. Such segments are returned to the 
system by 

FreeSegment: procedure [base: pointer]; 

For uses in which the page structure is already known, the following procedures are also 
provided. 

AllocatePages: procedure [npages: cardinal] returns [base: pointer]; 
AllocateResidentPages: procedure [npages: cardinal] returns [base: pointer]; 
PagesForWords: procedure [nwords: cardinal] returns [npages: cardinal]; 
FreePages: procedure [base: pointer]; 

Any storage obtained using AllocatePages or AllocateResidentPages is guaranteed to begin on a 
page boundary. 

Free Storage Package 

The following definitions are available in fspdefs. A zone is a block of storage containing 
embedded nodes, The length of either a zone or a node is 

BlockSize: type = integer [O..VMUmit/2]; — 15 bits. 

Each zone is headed by a ZoneHeader, which is a monitored record with the following public 
fields: 

• » « 

threshold: BlockSize, — minimum node size in zone 
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Zones are identified by pointers of type 
ZonePointer: type = pointer to ZoneHeader; 
Associated with each zone is a procedure of type 
Deallocator: type = procedure [pointer]; 

which is used to deallocate the storage used by the zone. The following Deallocator may be 
supplied when nothing is to be done to the storage being freed: 

DoNothingDeallocate: Deallocator; 

Zone Operations 

An arbitrary block of (uninterpreted) storage is converted to a zone by the procedure 

MakeNewZone: procedure [base: pointer, length: BlockSize, deallocate: Deallocator] 
returns [z: ZonePointer]; 

Such a block can alternatively be made an extension of an existing zone by calling 

AddToNewZone: procedure [ 

z: ZonePointer, base: pointer, length: BlockSize, deallocate: Deallocator]; 

The following procedures default DoNothingDeallocate as the Deallocator: 

MakeZone: procedure [base: pointer, length: BlockSize] returns [z: ZonePointer]; 

AddToZone: procedure [z: ZonePointer, base: pointer, length: BlockSize]; 

Unused areas of the zone are released by calling 
PruneZone: procedure [z: ZonePointer] returns [boolean]; 

which returns true if any areas were freed and false otherwise. 
A zone may be destroyed and all its storage freed by calling 
DestroyZone: procedure [z: ZonePointer]; 

No check is made for any nodes that are in use. 

Warning: This operation cannot be protected by the monitor, and can therefore result in 
severe errors if another process is inside the zone. 

Node Operations 

The largest node that can be allocated in a virgin block of size length is length -ZoneOverhead. 
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A node is allocated by 

MakeNode: procedure [z: ZonePointer, n: BlockSize] returns [pointer]; 

The value returned points to a block of n words; there is an additional hidden word of 
overhead (at offset-1) which must be preserved by users of the node. Nodes are 
sometimes split to satisfy allocation requests. Splitting within a zone z never generates 
fragments with size less than z.threshold, which is initialized to the minimum size of a 
free node. A request for a node of size n will produce a node with size in the range [n . . 
n+z.threshold). 

The actual size of an allocated node is returned by 

NodeSize: procedure [p: pointer] returns [BlockSize]; 

If after coalescing all free nodes, a node of the requested size cannot be found, 
NoRoomlnZone: signal [z: ZonePointer]; 

is raised. This signal can be resumed (after, e.g., adding to the zone), and another attempt to 
allocate and return a suitable node will be made. An allocated node is returned to the zone by 

FreeNode: procedure [z: ZonePointer, p: pointer]; 

Alternatively, m existing node can be split by calling 
SplitNode: procedure [z: ZonePointer, p: pointer, n: BlockSize]; 

the first n words of the node p remain allocated, and the remainder of the node is freed. 

When a zone z is created, the variable z.checking is initialized to false. If that variable is set to 
true, the zone is checked for consistency prior to each transaction involving that zone. A failure 
raises one of the following signals: 

InvalidZone, InvalidNode: error [pointer]; 



Allocation From The Heap 

Users which make extensive use of heap storage are encouraged to create their own heap from the 
above operations. The following procedures provide a simple interface to the free storage 
package. 

myHeap: FspDefs. ZonePointer *~ nil; 

GetSpace: procedure [nwords: cardinal] returns [p: pointer] b 
begin open SystemDefs, FspDefs; 
np: cardinal; 

p «- MakeNode[myHeap, nwords ! 
NoRoomlnZone => 

BEGIN 

np <- PagesForWords[nwords + ZoneOverhead + NodeOverhead]; 
AddToNewZone[ 
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myHeap, AllocateResidentPages[np], np*AltoDefs.PageSize, FreePages]; 

RESUME 
END]; 

RETURN 

end; 

FreeSpace: procedure [p: pointer] = 
begin 

FspDefs.FreeNode[myHeap, p]; 

RETURN 

end; 

GetString: procedure [nchars: cardinal] returns [s: string] = 

BEGIN 

s «- GetSpace[StringDefs.WordsForString[nchars]]; 
st «- [length: 0, maxlength: nchars, text:]; 

RETURN 
END; 

FreeString: procedure [s: string] = LOOPHOLE[FreeSpace]; 

InitHeap: procedure [npages: cardinal] = 
begin open SystemDefs, FspDefs; 
if myHeap # nil then EraseHeap[]; 
myHeap «- MakeNewZone[ 

AllocateResidentPages[npages], npages* AltoDefs.PageSize, FreePages]; 

RETURN 

end; 

EraseHeap: procedure = 
begin 

FspDefs.DestroyZone[myHeap]; 
myHeap *■ nil; 

RETURN 

end; 

Users which use the heap infrequently may use the system storage heap. The following 
definitions are available in systemdefs. The heap is managed by the free storage package; the 
appropriate zone pointer for use with the procedures described in the previous section is returned 
by 

HeapZone: procedure returns [ZonePointer]; 

The following procedures provide a specialized interface. 
AllocateHeapNode: procedure [nwords: cardinal] returns [p: pointer]; 
FreeHeapNode: procedure [p: pointer]; 
In addition, 
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AllocateHeapString: procedure [nchars: cardinal] returns [s: string]; 

allocates space for the body of a string in the heap. The field s.length is set to zero; 
s.maxlength is set to nchars. 

Such strings are freed by 

FreeHeapString: procedure [s: string]; 

If an allocation request cannot be satisfied from existing heap storage, an attempt is made to 
extend the heap with a block of appropriate size obtained from the segmentation machinery. 
The extension becomes a permanent part of the heap. 

The heap may be pruned by calling 

PruneHeap: procedure returns [boolean]; 

which returns true if any storage was returned to the segmentation machinery, and false 
otherwise. 
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May 1978 

streamio contains a set of procedures for convenient use of the character and string stream 
facilities in Mesa. The procedures of the streamio package are described below. The declarations 
necessary to use the procedures are in iodefs. 

streamio uses two streams, one for input and one for output. These may be gotten by calling: 
GetlnputStream, GetOutputStream: procedure returns [StreamHandle]; 

Returns the stream used for input or output, respectively. 
The streams may be changed by calling: 
SetlnputStream, SetOutputStream: procedure [StreamHandle]; 

Replaces the input or output stream, respectively. 

Character 10 
ReadChar: procedure returns [character]; 

Returns the next character from the InputStream. 
WriteChar: procedure [c: character]; 

The character c is written on the OutputStream. 

Definitions for control characters such as NUL, BS, TAB, LF, FF, CR, ESC, SP, DEL, and 
ControlA - ControlZ can be found in iodefs. 

String Input 

The procedures below read input from the InputStream. The following exceptional conditions 
may occur. 

LineOverflow: signal [s: string] returns [ns: string]; 

The input has filled the string s, the current contents of the string is passed as a 
parameter to the signal The catch phrase should return a string ns with more room. 
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Rubout: signal; 

The del key was typed during ReadEditedString. 
The procedures are: 
ReadEditedString: procedure [ 

S: STRING, t: PROCEDURE [CHARACTER] RETURNS [BOOLEAN], newstring: BOOLEAN] 
RETURNS [CHARACTER]; 

s contains (on return) the string read from the InputStream. The procedure t should 
return true if the character passed to it should terminate the string. If (newstring is 
true and the first input character is esc) or (newstring is false), then s is treated as if it 
had been read from InputStream (input characters are appended to it). Otherwise s is 
initialized to be empty before reading is begun. 

A string is read from the InputStream with the following editing characters recognized: 

tA, tH (bs) delete the last character 

tw, to delete the last word 

tx delete the line and start over 

tR retype the line 

tv quote the next character 

All characters except the terminating character are echoed on the OutputStream. The user 
supplied procedure t determines which character(s) terminate the string. The character returned 
is the character which terminated the string and is not echoed or included in the string. 

The following procedures all call ReadEditedString passing true for newstring. 

ReadString: procedure [s: string, t: procedure [character] returns [boolean]]; 

Like ReadEditedString except that the terminating character is echoed. No value is 
returned. 

ReadLine: procedure [s: string]; 

Reads from the InputStream up to the next carriage return character using 
ReadEditedString. The terminating character is not part of s. 

ReadID: procedure [s: string]; 

Uses ReadEditedString to read a string terminated with a space or carriage return into s. 
The terminating character is not echoed. 



String Output 

WriteString: procedure [s: string]; 

The string s is written on the OutputStream. 
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WriteLine: procedure [s: string]; 

The string s is written on the OutputStream followed by a carriage return. 

Number Input 

These procedures use the StringToNumber conversion procedures from the strings package. 

ReadNumber: procedure [default: unspecified, radix: cardinal] returns [unspecified]; 

ReadID followed by StringToNumber. The value default will be displayed if esc is typed, 
radix is a default value, use the "B" or "D" notation to force octal or decimal, radix values 
other than 8 or 10 cause unpredictable results. 

ReadDecimal: procedure returns [integer]; 

ReadID followed by StringToDecimal. 
ReadOctai: procedure returns [unspecified]; 

ReadID followed by StringToOctal. 

Number Output 

NumberFormat: type = record [ 

base: [2.. 36], zerofill, unsigned: boolean, columns: [0..255]]; 

refers to a number whose base is f.base; the field is f. columns wide; if f. zerofill, the 
extra columns are filled with zeros, otherwise spaces are used; if f. unsigned, the number 
is treated as unsigned. 

WriteNumber: procedure [val: unspecified, f: NumberFormat]; 

Equivalent to OutNumber[OutputStream, val, f], 

WriteDecimal: procedure [n: integer]; 

The value of n is converted to a character string of digits in base ten and output to the 
OutputStream. Negative numbers are written with a preceeding minus sign 0~). 

WriteOctal: procedure [n: unspecified]; 

The value of n is converted to a character string of digits in base eight and output to the 
OutputStream. The numbers are unsigned, i.e., -2 is written as 177776B. The "B" is 
appended to any number more than one digit long. 
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Initialization 

The Mesa system provides an instance of StreamlO which will obtain input from the keyboard 
and write output to the display. Client programs may create new instances of StreamlO to deal 
with other streams by writing: 

StreamlO: from "streamio"; 

imports . . . systemio: StreamlO . . . ; 

f: pointer to frame [StreamlO]; 
• ■ ■ 

f «• new systemio; 
START f; 

The the streams used for input and output can then be set by calling SetlnputStream or 
SetOutputStream. The desired stream procedures may be accessed by OPENing f or writing 
f.procedurename. 
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Streams provide a standard interface between programs and their sources of sequential input and 
their sinks for sequential output. A set of standard operations defined for all types of streams is 
sufficient for all ordinary input-output requirements. In addition, most streams have special 
(device dependent) operations defined for them; programs which use such operations thereby 
forfeit complete compatibility. 

Streams transmit information in atomic units called items. Usually an item is a character or a 
word, and this is the case for most of the streams supplied with Mesa. Of course, a stream 
supplied to a program must have the same ideas about the kind of item it handles as the program 
does; otherwise confusion will result. Normally, streams which transmit text use character 
items, and those which transmit binary information use words. 

Streams are passed about using StreamHandles, variants of which are produced by the (device 
dependent) procedures that create streams. A StreamHandle is a pointer to a variant record of 
type StreamObject, which is defined (in streamdefs) as follows: 

StreamHandle: type = pointer to StreamObject; 

KeyboardHandle: type = pointer to Keyboard StreamObject; 
DisplayHandie: type = pointer to Display StreamObject; 
DiskHandle: type = pointer to Disk StreamObject; 

StreamObject: type = record [ 
reset: procedure [StreamHandle], 
get: procedure [StreamHandle] returns [unspecified], 
putback: procedure [StreamHandle, unspecified], 
put: procedure [StreamHandle, unspecified], 
endof: procedure [StreamHandle] returns [boolean], 
destroy: procedure [StreamHandle], 
body: select type: * from 

Keyboard => . . . 

Display => . . . 

Disk => . . . 

Other => [data: pointer]; 

The procedures which create streams return descriminated pointers (a DiskHandle, for example), 
which can be assigned to variables of type StreamHandle without any loopholes. Most stream 
procedures (and all of the standard operations) expect StreamHandles (which can be matched by 
any descriminated pointer); they check at runtime for the appropriate stream type. 

Error conditions are reported in a fashion independent of the particular stream type, using the 
following definitions (not all error codes are applicable to all stream types); 
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StreamError: signal [stream: StreamHandle, error: StreamErrorCode]; 

StreamErrorCode: type = { 

StreamType, StreamAccess, StreamOperation, 
StreamPosition, StreamEnd, StreamBug}; 

As the definition implies, each stream object contains procedures that implement the standard 
stream operations, as described below (s is a StreamHandle, i is an item of the appropriate type, 
and "code error" means that signal StreamError[s, code] is raised): 

reset[s] restores the stream to some initial state, generally as close as possible to the state 
it is in just after it is created. 

get[s] :returns the next item; StreamAccess error if s cannot be read or if endof [s] is 
true before the call. 

putback[s, i] modifies the stream so that the next get[s] will return i and leave s in the 
state it was in before the putback. 

put[s, i] writes i into the stream as the next item; StreamAccess error if the stream 
cannot be written; StreamEnd error if there is no more space in the stream. 

endof [s] true if there are no more items to be gotten from s. For output streams, endof 
is device-dependent. 

destroy[s] destroys s in an orderly way, freeing the space it occupies. Note that this has 
nothing to do with deleting any underlying data structures or processes associated with the 
stream (like a disk file, for example, or the keyboard process). 

Each of these operations is defined more precisely in the descriptions of the individual stream 
types which appear separately. All of the stream routines produce the StreamType error when 
the variant of the StreamObject they are passed is not what they are expecting. See the Disk 
Streams, Display, and Keyboard sections for details of specific stream types. 

The Other variant of a StreamObject is provided so that clients can easily provide other types of 
streams using the same standard set of operations. The data field of an Other StreamObject 
should point to any additional data required by the particular stream. Clients with more than 
one type of Other stream should include a type code in this data (probably as a variant record). 



Alto/Mesa String Package 



64 



Alto/Mesa String Package 

May 1978 



This module contains procedures that implement various string operations. The necessary type 
and procedure declarations appear in stringdefs and are described below. (Constants defining 
word size, character size, etc. are in altodefs.) 

SubStringDescriptor: type = record [ 
base: string, 
offset, length: cardinal]; 

Substring: pointer to SubStringDescriptor; 

A SubStringDescriptor describes a region within a string. The first character is 
base[offset] and the last character is base[offset+length-1]. 

WordsForString: procedure [nchars: cardinal] returns [cardinal]; 

Calculates the number of words of storage needed to hold a string of length nchars. The 
value returned includes any system overhead for string storage. 



String Construction 

AppendChar: procedure [s: string, c: character]; 

Appends the character c to the end of the string s; s.length is updated; s.maxlength is 
unchanged. 

AppendString: procedure [to, from: string]; 

Appends the string from to the end of the string to; to.length is updated; to.maxlength is 
unchanged. 

AppendSubString: procedure [to: string, from: Substring]; 

Appends the substring in from to the end of the string in to; to.length is updated; 
to.maxlength is unchanged. 

StringBoundsFault: signal [s: string] returns [ns: string]; 

An attempt was made to increase the length of s to be larger than s.maxlength. The catch 
phrase should return a string ns with more room. 
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DeleteSubString: procedure [s: Substring]; 

Deletes the substring described by s from the string s.base; s.base.length is updated; 
s.base.maxlength is unchanged. 

String Comparison 

EqualString, EqualStrings: procedure [s1, s2: string] returns [boolean]; 

Returns true if s1 and s2 contain exactly the same characters. 

EquivalentString, EquivalentStrings: procedure [s1, s2: string] returns [boolean]; 

Returns true if s1 and s2 contain the same characters except for case shifts. Note: 
strings containing control characters may not be compared correctly. 

EqualSubString, EqualSubStrings: procedure [s1, s2: Substring] returns [boolean]; 

Analogous to EqualString and EqualStrings. 
EquivalentSubString, EquivalentSubStrings: procedure [s1, s2: Substring] returns [boolean]; 

Analogous to EquivalentString and EquivalentStrings. 

String to Binary Conversion 

StringToNumber: procedure [s: string, radix: cardinal] returns [unspecified]; 

The characters of s are interpreted as a number whose value is returned, radix is used in 
the conversion unless the "B" or "D" notation is used to force octal or decimal. Supplying 
radix values of other than 8 or 10 is not supported. 

StringToDecimal: procedure [s: string] returns [integer]; 

Calls StringToNumber[s, 10]. 
StringToOctal: procedure [s: string] returns [unspecified]; 

Calls StringToNumber[s, 8]. 

StringToLongNumber: procedure [s: string, radix: cardinal] returns [long integer]; 

The characters of s are interpreted as a long integer whose value is returned, radix is 
used in the conversion unless the "B" or "D" notation is used to force octal or decimal. 
Supplying radix values of other than 8 or 10 is not supported. 

InvalidNumber: SIGNAL; 

A string is not a valid number if it is empty or contains characters other than digits (a 
leading *- and trailing 'B or 'D with scale factor are allowed). 
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Binary to String Conversion 

AppendNumber: procedure [s: string, n, radix: cardinal]; 

The value of n is converted to text using radix and appended to s; radix should be in the 
interval [2. .36]. 

AppendDecimal: procedure [s: string, n: integer]; 

IF n < 0 then AppendChar[s, '-]; AppendNumber[s, ABS[n], 10]. 
AppendOctal: procedure [s: string]; 

AppendNumber[s, n, 8]; AppendChar[s, 'B], 

AppendLongNumber: procedure [s: string, n: long integer, radix: cardinal]; 

The value of n is converted to text using radix and appended to s; radix should be in the 
interval [2. .36], 
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timeconvert contains procedures that implement various operations on dates and times. The 
necessary type and procedure declarations appear in timedefs and are described below. 

PackedTime: type = lnlineDefs.LongCARDINAL; 

A PackedTime is the number of seconds since midnight January 1, 1901 GMT. 

31 

Fine point: a PackedTime is not a LONG INTEGER because the number of seconds has already exceeded 2 ). 

DefaultTime: PackedTime; 

UnpackedTime: type = record [ 

year: [0..2050], — years less than 1901 are not possible 

month: [0..12), — January = 0 

day: [0..31], — first day of month = 1 

hour: [0..24), 

minute: [0..60), 

second: [0..60), 

weekday: [0..6], — Monday = 0 
zone: [-12.. 12], — Pacific « 8 
dst: boolean]; 

CurrentDayTime: procedure returns [PackedTime]; 

Returns the current date and time in packed format. 

UnpackDT: procedure [PackedTime] returns [UnpackedTime]; 

Converts a packed format time to a more convenient unpacked format. If the argument 
is DefaultTime, the current time is used. 

PackDT: procedure [unp: UnpackedTime, computeDST: boolean] returns [PackedTime]; 

Converts unp into packed format. If computeDST is true, the time zone and daylight 
savings time are computed according to local conventions rather than taken from unp. If 
any of the fields of unp contain illegal values, PackDT will signal InvalidTime. 

InvalidTime: error; 

PackDT has discovered illegal values in the unpacked time. 

AppendDayTime: procedure [s: string, u: UnpackedTime]; 

Converts u to a text string of the form 12-Jan~78 14:56 and appends it to s. 
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AppendFullDayTime: procedure [s: string, u: UnpackedTime]; 

Like AppendDayTime except that the time zone is included, e.g. l-May-78 14:56 PDT. 
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Alto/Mesa Traps 

May 1978 



All traps generated by Mesa are converted into signals or errors of the same name. Except for 
the parity error and stack error traps, all of the signals described below are related to specific 
language features and are described in more detail in the Mesa Language Manual (see the index). 

StartFault: signal [dest: GIobalFrameHandle]; 

An attempt was made to start or restart the frame dest, but it is not a valid global frame. 
Usually this means that a module or program was not bound, a program being restarted 
does not stop, or a module that has parameters is being started as a result of a start trap. 

ControlFault: signal [source: FrameHandle] returns [ControlLink]; 

An attempt was made to transfer to a null control link while executing in the frame 
source. Usually this means some external links have been clobbered. This signal can be 
resumed with a control link that will be used to retry the transfer. 

UnboundProcedure: signal [dest: ControlLink] returns [ControlLink]; 

An attempt was made to transfer to dest but it had an unbound tag. Usually this means 
some external links have not been bound or the gft entry of dest is null (probably a 
deleted module). This signal can be resumed with a control link that will be used to retry 
the transfer. 

• LinkageFault: error; 

A transfer has been attempted through a port that has not been connected to some other 
port or procedure (the link field of the port was null). 

PortFault: error; 

A transfer has been attempted to a port which is not pending (the frame field of the 
destination port is null). This error is used to handle the startup transients common in a 
configuration of coroutines. 

ParityError: signal [address: pointer]; 

A parity error has occured in the word pointed to by address. 
PhantomParityError: signal; 

The parity error process was started, but a sweep through memory found no errors. 
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StackError: signal [FrameHandle]; 

The stack has either overflowed or underf lowed while executing in the designated frame. 
Usually this means that either some code has been smashed or some external link is 
incorrect. 

Fine point: external links may be incorrect because the user forgot to rebind after a recompilation, or 
procedure variables were incorrectly LOOPHOLED. 
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Alto/Mesa Window Package 

May 1978 



Note: This document describes facilities used in Mesa systems released before Mesa 4.0. This 
package is being phased out and is no longer supported. The package windowpackage is 
available to those who wish to use it during a transition to other display facilities. 

The purpose of the window package is to provide the basic facilities for a wide range of user 
requirements in dealing with the bitmap display. Since the subject of display illusions has been 
one of the most active and innovative, these facilities have been built in such a way as to support 
the currently known popular ways of dealing with the display and hopefully will provide the 
primitives for yet more powerful facilities. This documentation is divided into the following 
sections: 

Bitmaps 

Rectangles 

Display Streams 

Windows 

Menus 

Selections 

Fonts 

The window package modules are divided into two major sections: those that deal with the 
hardware or physical characteristics of the display and those that use them. Bitmaps and 
Rectangles are intended to provide all of the lower level facilities required to support the display, 
while Display Streams, Windows and Menus are built using these primitives. Facilities are 
provided for creating and manipulating bitmaps and rectangles within them, for associating 
streams and/or windows with rectangles, and for displaying and marking menus. 



Bitmaps 

The most primitive objects in the window package are bitmaps. A BitmapObject contains all the 
data about the physical characteristics of an actual display bitmap (suitable for displaying), which 
is defined (in rectangledefs) as follows: 

BMHandle: type = pointer to BitmapObject; 

BitmapObject: type = record [ 

link: BMHandle, — # nil iff being displayed 

rectangles: Rptr, — list of rectangles for this map 

deb: DCBptr, — address of block to be used for DCB 

addr: BMptr, — its address 

words: cardinal, -.- size of map (in words) 

wordsper line : [ 0 . . max wordsper line ] , 

xO: xCoord, — x,y of upper left corner 

yO: y Coord, 

width: xCoord, — in bits (but even words) 
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height: yCoord, — in real scan lines 
indenting: [0..77B], — in units of 16 bits 
resolution: restype, 
background: backgtype]; 

where the above types are defined as follows: 

restype: type = {high, low}; 
backgtype: type = {white, black}; 
xCoord: type = [0..606]; 
yCoord: type = [0..808]; 

Initially, the window package establishes a default bitmap, which is obtained by calling: 

GetDefaultBitmap: procedure returns [BMHandle]; 

New bitmaps may be created by calling: 

CreateBitmap: procedure [pagesformap, wordsperline: cardinal] returns [BMHandle]; 

This procedure creates a BitmapObject, initializes it, allocates the requested space for the bitmap 
and initializes the map to all zeros. It also allocates a DCB for this map and initializes it in 
anticipation of being displayed. 

A bitmap is destroyed by calling: 

DestroyBitmap: procedure [mapdata: BMHandle] returns [pointer]; 

Before destroying a bitmap, all rectangles contained within it must be destroyed; otherwise, 
you will get the signal 

BitmapError: signal [bitmap: BMHandle, error: BitmapErrorCode]; 
BitmapErrorCode: type = {BitmapOperation}; 

Bitmap Manipulation 

The following routines are provided for altering and manipulating bitmap objects in a uniform 
way. You may alter the size and/or shape of a display bitmap by calling: 

ReallocateBitmap: procedure [mapdata: BMHandle, pagesformap, wordsperline: cardinal]; 

This procedure may also be used to deallocate the memory used for a bitmap and subsequently 
reallocate it. 

If you decide to alter any of the fields of a bitmap object and wish to have the effect of that 
alteration reflected in the hardware (e.g. change background from white to black) call: 

UpdateBitmap: procedure [mapdata: BMHandle] returns [DCBptr]; 

The above call returns the real DCB address for the specified BitmapObject because DCB's 
(as required by the hardware) must be even word aligned and the field in the 
BitmapObject may or may not be aligned. 
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The following two procedures are supplied to actually display (undisplay) a bitmap: 

Display Bitmap: procedure [mapdata: BMHandle]; 

UnDisplayBitmap: procedure [mapdata: BMHandle]; 

The following two procedures turn the whole display off and on: 

DisplayOff: procedure [backgtype]; 

DisplayOn: procedure; 

When the display is off the memory occupied by the default bitmap and font is released and the 
screen is left white or black according th the parameter. DisplayOn will reallocate the bitmap but 
will not redisplay the old data (see RepaintDisplayWindows below). 



Rectangles 

Rectangles describe arbitrary rectangular regions within a bitmap. Together with bitmaps, 
rectangles and the procedures for manipulating them implement the most primitive functions of 
the window package. (Definitions are in rectangledefs) 

Rptr: type = pointer to Rectangle; 

Rectangle: type = record [ 
link: Rptr, 
visible: boolean, 
options: ROptions, 
bitmap: BMHandle, 

xO, width, cw: xCoord, — relative to bitmap origin 

yO, height, eh: yCoord]; — cw/ch are clipped width/height 

ROptions: type = RECORD [ 

Notelnvisible: boolean, -- signal if rectangle off bitmap 
NoteOverflow: boolean]; -- signal if storing outside 

New rectangles are created by calling the procedure: 

CreateRectangle: procedure [bitmap: BMHandle, xO, width: xCoord, yO, height: yCoord] 
returns [Rptr]; 

V 

Writing of text at arbitrary locations within a rectangle is accomplished by: 

WriteRectangleChar: procedure [ 

rectangle: Rptr, x: xCoord, y: yCoord, char: character, pfont: FAptr] 
returns [xCoord, yCoord]; 

WriteRectangleString: procedure [ 

rectangle: Rptr, x: xCoord, y: yCoord, str: string, pfont: FAptr] 
returns [xCoord, yCoord]; 

where x and y are relative to the rectangle origin. If the rectangle is not visible (e.g. outside the 
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bounds of the bitmap) or x or y is outside the rectangle then one of the signals NotVisible, 
RightOverflow or BottomOverflow is generated. 

The following procedures will handle clipping situations for rectangle overflow either to the right 
or off the bottom. In the current implementation they will not allow a rectangle to either go off 
the top or to the left of a bitmap. 

Rectangles may be moved or their size altered by invoking: 
MoveRectangle: procedure [rectangle: Rptr, x: xCoord, y: yCoord]; 
GrowRectangle: procedure [rectangle: Rptr, width: xCoord, height: yCoord]; 
where x, y, width and height are relative to the bitmap origin. 

Rectangle Utilities 

The following procedures implement commonly used operations on rectangles. They are by no 
means a complete set but are simply the ones used in providing the basic window package 
facilities. 

Coordinates are relative to the rectangle origin. 

DrawBoxInRectangle: procedure [rectangle: Rptr, xO, width: xCoord, yO, height: yCoord]; 

draws a rectangular box with lines of width one inside the supplied rectangle. 

ScrollBoxInRectangle: procedure [ 

rectangle: Rptr, xO, width: xCoord, yO, height: yCoord, incr: integer]; 

will scroll the rectangular region within the supplied rectangle defined by xO, yO, width, 
and height either up or down as specified by incr (+ = up). 

InvertBoxInRectangle: procedure [rectangle: Rptr, xO, width: xCoord, yO, height: yCoord]; 

will video reverse the rectangular region within the supplied rectangle defined by xO, yO, 
width, and height. 

ClearBoxInRectangle: procedure [ 

rectangle: Rptr, xO, width: xCoord, yO, height: yCoord, gray: GrayPtr]; 

will clear the rectangular region within the supplied rectangle defined by xO, yO, width, 
and height to the supplied gray pattern (e.g. 0 a clear -1 = black etc.). 

The display facilities allow you to alter both the bitmap and the position of a rectangle within a 
bitmap such that it is possible for a rectangle to be not visible (entirely outside the bounds of the 
bitmap). You may determine if a rectangle is visible by calling 

IsRectangleVisible: procedure [rectangle: Rptr] returns [boolean]; 
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Exceptional Conditions 

The following exception conditions are optionally reported to the user based upon the setting of 
the rectangle option flags Notelnvisible and NoteOverflow. 

RectangleError: signal [rectangle: Rptr, error: RectangleErrorCode]; 

RectangleErrorCode: type = {RightOverflow, BottomOverflow, NotVisible}; 

Coordinate Conversion Routines 

The following procedures allow you to convert between cursor, rectangle and bitmap coordinates. 
They worry ajxwt indenting and other displayed bitmaps. 

CursorToMapCoords: procedure [mapdata: BMHandle, x: xCoord, y: yCoord] 
returns [xCoord, yCoord]; 

Converts the cursor coordinates (display origin relative) to bitmap coordinates (bitmap 
origin relative). 

RectangleToMapCoords: procedure [rectangle: Rptr, x: xCoord, y: yCoord] 
returns [xCoord, yCoord]; 

Converts rectangle coordinates (rectangle origin relative) to bitmap coordinates (bitmap 
origin relative). 

CursorToRecCoords: procedure [rectangle: Rptr, x: xCoord, y: yCoord] 
returns [xCoord, yCoord]; 

Converts cursor coordinates (display origin relative) to rectangle coordinates (rectangle 
origin relative). 



Display Streams 

Display streams are provided in the window package to perform teletype simulation operations 
that are commonly associated with display based systems. Display streams are associated with a 
previously created rectangle at stream creation time. For a more complete desciption of streams 
see the Streams documentation. The window package comes equipped with a 
DefauItDisplay Stream. Interpretation of the standard stream operations is as follows: 

reset[s] is a no-op. 

get[s] produces a StreamAccess error. 

putback[s,i] produces a StreamAccess error. 

put[s,i] writes the character i in the next character position. Options are provided for 
line wrapping/truncation and scrolling/discarding. 

endof[s] produces a StreamAccess error. 

destroy[s] destroys s in an orderly way, freeing the space it occupies. If s is the default 
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display stream, the StreamOperation error results. 

Initially, the default display stream is defined by a rectangle which occupies the entire default 
bitmap. The DisplayHandle is returned by the procedure 

GetDefaultDisplayStream: procedure returns [DisplayHandle]; 

Any number of display streams may be created, using the procedure 

CreateDisplay Stream: procedure [rectangle: Rptr] returns [DisplayHandle]; 

where rectangle is a pointer to a rectangle object associated with a bitmap. It should be noted 
that display streams by themselves provide no facilities for dealing with rectangles that overlap 
(e.g. the characters are simply OR'ed together). However, facilities are provided by windows for 
dealing with this situation in an orderly manner. 

The following procedures implement backspace character and line functions: 
ClearDisplayChar: procedure [stream: StreamHandle, char: character]; 
ClearCurrentLine: procedure [stream: StreamHandle]; 
ClearDisplayLine: procedure [stream: StreamHandle, line: cardinal]; 

The requirement to pass the character to be erased in ClearDisplayChar is necessary because the 
stream retains no memory of what characters were displayed. 



Windows 

Windows provide a uniform mechanism for managing the data (text or bit arrays) contained in 
rectangles. Windows and the supplied procedures are designed to allow the user to recreate or 
reposition a view in a rectangle in a standard manner. (Definitions are in windowdefs) 

WindowType: type = {clear, random, scratch, file, scriptfile}; 

WindowHandle: type = pointer to DisplayWindow; 

DisplayWindow: type = RECORD [ 
link: WindowHandle, 
type: WindowType, 
name: string, 
menu: MenuHandle, 

displayproc: procedure [WindowHandle], 

rectangle: Rptr, 

ds: DisplayHandle, 

ks: StreamHandle, 

file: DiskHandle, 

fileindex: Streamlndex, 

tempindex: Streamlndex, 

eof index: Streamlndex, 

selection: Selection]; 
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Selection: type = record [ 
leftx, rightx: xCoord, 
leftline, rightline: cardinal, 
leftindex, rightindex: Streamlndex]; 

New display windows may be created by calling 

CreateDisplay Window: procedure [ 

type: WindowType, r: Rptr, ds: Display Handle, ks: StreamHandle, name: string] 
returns [WindowHandle]; 

Conversely, display windows may be destroyed and all data associated with them released by 
invoking 

Destroy Display Window: procedure [w: WindowHandle]; 

It is often desirable to be able to transform one type of window into another (e.g. load a file into 
a scratch window). The following procedure undoes the old attributes and sets up new ones: 

Alter WindowType: procedure [w: WindowHandle, type: WindowType, name: string]; 

Refreshing both the border and content of a window is accomplished via the following 
procedure. Actual content refreshing is accomplished by dispatching to a user supplied (or 
defaulted) procedure. 

PaintDisplayWindow: procedure [w: WindowHandle]; 

The concept of a window being current (e.g. on top) is central to this implementation of display 
windows. Windows are maintained in a ring in the order they were last current. To make a 
window current (which also refreshes its contents) call: 

SetCurrentDisplayWindow: procedure [w: WindowHandle]; 

At any point you may determine which window is current by calling: 

GetCurrentDisplay Window: procedure returns [WindowHandle]; 

If the current window is type scratch or scriptfile, calling: 

BlinkCursor: procedure returns [boolean]; 

will blink a software "cursor" at the position where the next character will be displayed. (This 
software cursor is a property of windows and should not be confused with the hardware cursor 
which is a part of the display hardware.) Each call changes the state of the cursor from "on" to 
"off" or vice versa. BlinkCursor returns true if the last call changed the cursor state to on. The 
cursor is always turned off before a character is displayed or erased and before the window is 
moved or repainted. 

To determine which window (if any) the hardware cursor may be in call: \ 
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FindDisplay Window: procedure [x: xCoord, y: yCoord] 
returns [WindowHandle, xCoord, yCoord]; 

Coordinates are cursor coordinates (display origin relative). If WindowHandle is nil then the 
supplied x, y are not in any window. If a non-NiL WindowHandle is returned then the x, y are 
converted into rectangle coordinates (rectangle origin relative) and returned also. 

For file type windows you may alter the file being displayed by invoking: 

SetFileForWindow: procedure [w: WindowHandle, name: string]; 

SetFileHandleForWindow: procedure [w: WindowHandle, f: FileHandle, name: string]; 

Scratch, scriptfile and file type windows use a stream to manage their data contents. You may 
reposition the displayed contents of these windows by calling: 

SetlndexForWindow: procedure [w: WindowHandle, index: Streamlndex]; 

SetPositionForWindow: procedure [w: WindowHandle, position: cardinal]; 

Exceptional Conditions 

In general the procedures implementing windows do not generate signals or errors but rather 
attempt to muddle through whatever nonsense you supplied or tried to do. This results in 
coercing coordinates and turning funny calls into NOPs in most cases. 



Menus 

Menus supply a uniform command specification facility. The current implementation is very 
simple and just provides for a correspondence between a keyword and a procedure to be invoked 
if that key word is selected The display algorithm and selection technique are built-in. 
(Definitions are in menudefs) 

MenuHandle: type = pointer to MenuObject; 

MenuObject: type = record [ 
link: MenuHandle, 
index: integer, 
width: xCoord, 
rectangle: Rptr, 
menuseg: FileSegmentHandle, 
dataseg: FileSegmentHandle, 
array: MenuArray]; 

MenuArray: type = descriptor for array of Menultem; 

Menultem: type = record [ 
keyword: string, 

proc: procedure [unspecified, xCoord, yCoord]]; 
New MenuObjects are created and destroyed by calling: 
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CreateMenu: procedure [array: MenuArray] returns [MenuHandle]; 
DestroyMenu: procedure [menu: MenuHandle]; 

A menu is actually displayed on the display screen by calling: 

DisplayMenu: procedure [menu: MenuHandle, mapdata: BMHandle, x: xCoord, y: yCoord]; 

Coordinates are bitmap origin relative. This procedure saves the contents of the bitmap to be 
overlayed if the size is not too big, so it may be restored later. 

To take a menu down and restore the previous contents of the bitmap call: 

ClearMenu: procedure [menu: MenuHandle]; 

Items in a displayed menu are marked as selected by invoking: 

MarkMenultem: procedure [menu: MenuHandle, index: integer]; 

The current implementation assumes that only one menu item will be marked at a time. 
Therefore simply marking a new item will unmark the currently marked item (if any). Marking 
is currently done by video reversal. 

Exceptional Conditions 

There is currently no checking to ensure that you do not attempt to clear non-displayed menus or 
other such nonsense. If you do you are on your own. 

Selections 

A selection is associated with each window. Whenever the window is refreshed, the current 
selection gets updated. (Definitions are in windowdefs) 

To find out the line number, horizontal position, width and stream index of the character that is 
located at a hardware cursor (display relative) position, call: 

ResolveBugToPosition: procedure [w: WindowHandle, x: xCoord, y: yCoord] 
returns [cardinal, xCoord, cardinal, Streamlndex]; 

You can get the current selection of a' window by calling: 

GetSelection: procedure [w: WindowHandle] returns [string]; 

which returns the text of a selection in a string allocated from the Mesa system heap (see the 
Storage documentation). 

The old selection is unmarked and the new selection is marked by calling: 
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MakeSelection: procedure [w: WindowHandle, sel: pointer to Selection]; 
A selection is video reversed by calling: 
MarkSelection: procedure [w: WindowHandle]; 

The current selection of a window that is being refreshed is updated (ie. checked for visibility) 
by calling: 

UpdateSelection: procedure [w: WindowHandle]; 

Fonts 

Font procedures assume the standard font format (".Al" files). Only the most simple font 
procedures are supplied as follows. See rectangledefs for more details. 

ComputeCharWidth: procedure [char: character, font: pointer] returns [cardinal]; 

GetDefaultFont: procedure returns [FAptr: cardinal]; 

returns the default font 
LoadFont: procedure [segment: FileSegmentHandle] returns [p: Fptr]; 

swaps in and locks the font segment 
GetFont: procedure [filename: string] returns [FileSegmentHandle]; 

allocates space and creates a segment for a font 

Starting the Window Package 

The window package requires startup parameters. The following modules must be explicitly 
STARTed: 

RectangleDefs.RectanglesB: program [pagesformap, mapwordsperline: cardinal]; 
pagesformap and mapwordsperline define the initial size and shape of the default bitmap. Mesa 

3.0 used pagesformap: 40, mapwordsperline: 30. } 

WindowDefs.WindowsB: program [string]; 

specifying the name of the default window (which is a scriptfile window). 



